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Preface 


This document is one of a series describing the SPERRY UNIVAC Information Management 
system 90 (IMS 90) for users of Operating System/3 (OS/3). An introduction to IMS 90, 
UP-8816 (current version), provides an overview of IMS 90 software and its use. The 
system support functions user guide/programmer reference, UP-8364 (current version), is 
directed to systems analysts and IMS 90 administrators. It describes communications 
network structuring, pre-online processing, and IMS 90 initiation, execution, and recovery 
procedures. This applications user guide/programmer reference (UP-8614) is intended for 
use with the systems support functions manual and is directed to IMS 90 application 
programmers and terminal operators who must prepare and process user applications. 
Subjects described are: 


=  ## Preparation of data definitions for use by the uniform inquiry update element 
(UNIQUE) or user-written action programs 


= Preparation of action programs in COBOL, RPG Il, or basic assembly language (BAL) 
=  ##Preparation of edit tables for use with user-written action programs 

2 + Terminal operation, including operation of the master terminal and user terminals 

= Transaction processing via UNIQUE 

= Batch transaction processing 

IMS 90 users wishing to access a DMS 90 data base from action programs should read 
the IMS 90/DMS 90 interface user guide/programmer reference, UP-8748 (current 


version). Also available is the IMS 90 terminal user commands, UP-8741 (current version), 
which is a pocket reference card. 
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1. Introduction 


1.1. OVERVIEW 


The SPERRY UNIVAC Information Management System 90 (IMS 90) is an interactive, 
transaction-oriented file management system. It is interactive because it operates on the 


principle that a question-and-answer dialog is maintained between the terminal operator 
and IMS 90. 


The basic unit of work in IMS 90 is an action. An input message, the processing of it by 

one or more action programs, and at least one output message define an action. 

Accordingly, a sequence of one or more related actions defines a transaction. IMS 90 is 

transaction-oriented because all processing is triggered by an input message or question 
@ that requires at least one output message or answer. 


To process transactions, Sperry Univac supplies a set of action programs called the 
uniform inquiry update element (UNIQUE), activated by commands from remote terminals, 
as a component of IMS 90. For convenience in processing messages, you can either 
employ the IMS 90 UNIQUE action programs or write your own action programs in 
COBOL, report program generator {I (RPG Il), or basic assembly language (BAL). 


IMS 90 manages user logical and defined files. User logical files are collections of logical 
records created on physical devices and accessed via the standard access methods (DAM, 
MIRAM, ISAM, or SAM. To access IRAM files, you must define them as MIRAM files at 
configuration time.) In contrast, defined files are collections of defined records that the 
defined record management component of IMS 90 composes from one or more logical disk 
records according to a user-supplied data definition. You can also protect defined files by 
assigning passwords. Built into the IMS 90 modular components are data verification and 
protection procedures, and scheduling and queueing procedures. IMS 90 file access 
techniques are compatible with existing programming and file structures. IMS 90 also 
allows you to access data base management system 90 (DMS 90) data bases. 


The interactive transaction processing capabilities of IMS 90 rely on _ its 
communications/data management support. IMS 90 uses the SPERRY UNIVAC Integrated 
Communications Access Method (ICAM) Transaction Control Interface (TCI) to Support 
terminal communications. Refer to the IMS 90 system support functions user 

© guide/programmer reference, UP-8364 (current version) for information about setting up a 
communications interface. 
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IMS 90 provides a terminal command repertoire to assist terminal operators in using & 
remote terminals. A master terminal command repertoire, also provided by IMS 90, 

enables the master terminal operator to control terminals assigned to IMS 90 and monitor 

the system. : 


When inquiries or updates to files are initiated from remote terminals, IMS 90 components 
such as action scheduling, file management, and internal message control facilitate rapid 
processing. Application, administration, and operation of the IMS 90 transaction 


processing system are performed during pre-online, online, and offline processing by IMS 
90 operations and user activities. 


1.1.1. IMS 90 Operations 


1.1.1.1. Pre-online Processing 

IMS 90 pre-online processing employs the IMS 90 utilities and processors that prepare 

and tailor the system for processing transactions online. IMS 90 pre-online processing 

includes: 

= ~=initialization of the named record file via the NAMEREC utility; 

= definition of passwords via the same NAMEREC file utility; ; 
™ processing of user data definitions by the data definition processor; 


# configuration of the online IMS 90 system from user-specified parameters; and 


= generation of edit tables. 


1.1.1.2. Online Processing 


IMS 90 online processing employs components that control the interactive processing of 
transactions. 


Online processing includes: 

= system startup and shutdown procedures; 

= internal message control including terminal control functions; 

#® scheduling and loading of UNIQUE or user-written action programs; 
= IMS 90 and user file management; and 


= activation record control. 
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1.1.1.3. Offline Processing 


IMS 90 offline processing handles the recovery of user files left damaged or in an 
inconsistent state. It includes: 


= the offline recovery utility (ZC#TRC); and 
= the tape copy routine (ZC#HTCP). 


A more detailed description of the IMS 90 components and their roles in pre-online, 
online, and offline processing is provided in the IMS 90 system support functions user 
guide/programmer reference, UP-8364 (current version). System preparation functions, 
Startup/shutdown procedures, and recovery processing are also described in UP-8364. 
Applications preparation and processing, including action programming, data definition, 
edit table generation, and terminal operation, are described in this document. 


1.1.2. User Activities 


The most important activities you perform are defining data (required for UNIQUE, optional 
for user action programs); configuring the online IMS 90 system (mandatory); writing 
action programs (optional); and processing your transactions from remote terminals, using 
UNIQUE or user action programs. 


In addition, user activities include the following optional pre-online and offline operations: 
= running the NAMEREC utility to initialize the named record file and define passwords; 
= defining edit tables for input message formatting and data validation; and 


= recovering user files, if necessary. 


1.1.2.1. Defining Data 


One of your first tasks is to define the data to be used in your IMS 90 application. To do 
this, you must write a data definition if you are going to use UNIQUE or you may optionally 
write one for use with your own action programs. (User action programs can also access 
conventional DAM, MIRAM, IRAM, ISAM, and SAM files.) A data definition describes a 
defined file, containing defined records. These defined records are redefinitions of user 
logical records from existing physical files. Because the actual data for these defined 
records exists as logical records in one or more user files, the defined record management 
component of IMS 90 needs to know only where all parts of each defined record can be 
located in your files so that it can construct the defined record when an action program 
calls for it. This location information is contained in a data definition record which the data 
definition processor places in the IMS 90 internal file, NAMEREC. 
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1.1.2.2. Configuring IMS 90 


The user configures the IMS 90 system by preparing the job control stream and 
configurator input, and by running the configurator job. A job control proc (jproc), 
IMSCONF, performs five job steps: communications control area (CCA) linkage, internal file 
initialization, configuration, assembly, and online linkage. 


User-specified configurator input consists of the following sections that define IMS 90 
characteristics. 


NETWORK TERMINAL OPTIONS ACTION FILE 
GENERAL TRANSACT TIMEOUTS PROGRAM DRCRDMGT 


For detailed discussion of IMS 90 configuration procedures, see the IMS 90 system 
Support functions user guide/programmer reference, UP-8364 (current version). 


1.1.2.3. Writing Action Programs 


Action programs are written to process transactions (Sequences of one or more actions). 
Action programs can be user-written or supplied by IMS 90. All action programs operate 
under the application management component of IMS 90 to process input messages and 
generate output messages. 


User action programs may be written in COBOL, Report Program Generator II (RPG Il), or 
Basic Assembly Language (BAL). The series of action programs supplied by IMS 90 is. 
identified as the uniform inquiry update element (UNIQUE). No user action programming is 
required if you plan to process all your transactions through UNIQUE. 


1.1.2.4. Using Uniform Inquiry Update Element (UNIQUE) 


The Sperry Univac supplied series of action programs called UNIQUE accesses and 
updates defined files via a group of UNIQUE commands issued by the user at the terminal. 
The defined record management (DRM) component of IMS 90 handles the defined file 
accessing operations. Section 6 of this document provides a detailed discussion of 
UNIQUE. | 


1.1.2.5. Operating Terminals 


There are two sets of terminal commands ~ master and standard. Master. terminal 
commands control and monitor the overall system and communications network. The 
Standard terminal commands control message processing at the terminal. All terminal 
commands begin with the letters ZZ. Section 5 of this document discusses terminal 
operation in detail. 
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1.2. APPLICABILITY 


IMS 90 is ideally suited for inquiry/update-oriented file processing applications. Some of 
the most typical applications are: 


= Inventory control 

= Order shipping 

2 ~@§€«6Insurance 

= Medical/hospital 

= Interactive data collection 
a =§=6Information management 
= Library recall 

« Warehouse management 
= Computer-aided instruction 
=# One-time report generation 
= Job shop operation 


IMS 90 is especially suited to any application where ease of use, reliable performance, 
and integrity in data manipulation and information management are the primary concerns. 
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2. Data Definition 


2.1. INTRODUCTION 


You write a data definition to describe a defined file. IMS 90 constructs defined files from 
elements of existing ISAM, MIRAM, and DAM disk files and from data base 
subschemas according to the data definition you write and submit to the data definition 
processor. 


If you decide to use the IMS 90-supplied uniform inquiry update element (UNIQUE), you 
must write a data definition because UNIQUE accesses user files only via defined files. 
When writing your own action programs, you can use defined files or you can call on IMS 
90 file management to access your conventional DAM, ISAM, MIRAM, or SAM files 
directly. (To access IRAM files, you must define them as MIRAM files at configuration 
time.) Your COBOL action programs can also directly access a DMS 90 data base. Refer to 
the IMS 90/DMS 90 interface user guide/programmer reference, UP-8748 (current 
version). 


In addition to defining records and file structures in your data definition, you define 
allowable functions (retrieve, modify, add, delete). The defined record management (DRM) 
portion of IMS 90 file management provides strong data integrity during defined file 
manipulation. Before executing any operation that changes disk files, DRM verifies that 
the change is allowed and that new values are within the limits you defined in the data 
definition. 


IMS 90 accesses defined records by keys. For this reason, IMS 90 must construct defined 
records from indexed files (ISAM or MIRAM) or a data base subschema. It can also use 
nonindexed files (DAM or MIRAM), but only in combination with indexed files or a 
subschema. 


Because the formats for data definition are similar to COBOL data division formats, you 
should have some knowledge of COBOL before you write a data definition. 


+ 4 
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2.1.1. Data Flow in IMS 90 


Action programs access user data files through IMS 90 file management. When a user- 
written action program requests a logical input record from IMS 90, the file management 
component of IMS 90 issues a request for the record to OS/3 data management. Data 
management, interfacing between IMS 90 and the user data file, retrieves the physical 
record (or block) containing the logical record wanted, and passes the logical record to IMS 
90 file management. In turn, IMS 90 file management passes the desired logical record to 
the action program. Similarly, data management receives logical record output from IMS 
90 and transfers physical records to the user data files. These relationships are illustrated 
in Figure 2-1. 


ACTION PROGRAMS 


USER-WRITTEN 
ACTION LOGICAL LOGICAL PHYSICAL 


SROCHAMIG RECORDS | RECORDS RECORDS 


MANAGEMENT 





Figure 2—7. Data Flow Between Action Programs and User Data Files 


There also is a different type of record that can be requested by a user-written action 
program — the defined record. A defined record comprises: 


# all or part of a logical record from one of the user data files; 
= il or parts of several logical records from the same user data file; or 
= all or parts of several logical records from different user data files. 


It is the DRM portion of IMS 90 file management that handles requests from action 
programs for defined records. DRM determines which logical records and what parts of 
them are required and from which user data files they are to be retrieved by data 
management. DRM then issues the necessary calls to data management, receives the 
logical records as input, and constructs the defined record that is expected by the action 
program. Finally, DRM passes the defined record to the program requesting it. Figure 2-2 
illustrates these activities. 
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USER- PHYSICAL 


WRITTEN | 
ACTION DEFINED | 
PROGRAMS RECORDS 
OR DATA 


| 
| 
| 
| 
| 


Figure 2—2. Flow of Defined Records to Action Programs via IMS 90 





The information DRM needs for calling logical records to construct defined records, 
requested by action programs, is contained in the data definition record. When action 
programs request defined records in response to some terminal input, DRM accesses the 
data definition record (2.1.2) in an internal IMS 90 disk file called the named record 
(NAMEREC) file. 


A terminal operator who is using the commands of the UNIQUE language for file query 
operations receives only defined records, displayed or listed at the terminal as specified by 
the IMS 90 action programs that implement UNIQUE. Using UNIQUE, the terminal operator 
accesses the user data files only through DRM. User-written action programs, on the other 
hand, provide the terminal operator with defined records, obtained through DRM, or with 
logical records, obtained from the user data files through the other components of IMS 90 
file management. Similarly, updating information input to IMS 90 through a UNIQUE 
action program is received by DRM as defined records. A user-written action program 
provides both defined records to DRM and logical records to IMS 90 file management. 
Action programs using both defined records and logical records, however, cannot directly 
access a logical record that is accessed by the defined record. Figure 2-3 illustrates the 
data flow between both types of action programs and disk storage, indicating in schematic 
form the complete processing of logical and defined records. 
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Figure 2—3. Data Flow Between Action Programs and Disk Storage 


The collection of defined records extracted from user data files and passed by DRM to 
— action programs forms the defined file. 
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2.1.2. Creating Data Definition Records 


The data definition records needed by DRM to access defined files are created by writing 
data definitions, using the data definition language described in 2.3. These data definitions 
are processed by the data definition processor which is similar to a COBOL compiler. The 
data definition processor writes the patterns for all defined records and defined files into 
the NAMEREC file and produces a diagnostic listing. Figure 2-4 illustrates the use of the 
data definition processor to create data definition records. 







DATA 
DEFINITION 
SOURCE CODE 












DATA 
DEFINITION 
PROCESSOR 







DATA 
DEFINITION 
RECORD 









DIAGNOSTIC 
LISTING 






Figure 2—4. Data Definition Processing 


2.2. DEFINED FILE 


The defined file can be regarded as an indexed sequential file containing defined records 
tailored to the needs of an application. The tailoring begins with preliminary offline 
processing when you define to the IMS 90 data definition processor the data you want 
extracted for use in your specific application. This data definition simplifies both user 
action programs and UNIQUE because an action program need address only one defined 
file rather than several logical files whose records have to be matched and processed 
together in main storage. Defined files require no additional storage because they exist 
only by description and consist of all or parts of existing user data files extracted by DRM. 
The only storage space needed is disk storage space (NAMEREC file) to hold the data 
definition records. 


Action programmers think of a defined file as an indexed sequential file containing records 
to be accessed via IMS 90 file I/O functions in the action program. It is possible for a 
defined file to be identical to an ISAM file. Other defined files can consist of different 
descriptions of the same user data file. 


Terminal operators display or list defined records on the terminal. The tmage they see 
informs them of the defined file structure that they are querying and updating. 
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2.2.1. Hierarchical Structure 


A defined file that contains more than one type of defined record has a hierarchical 
structure in which defined records have parent, child, and fraternal relationships. In Figure 
2-5, defined record Al is a parent to the child records B1, B2, and B3. But B1 ts also a 
parent to C1, C2, and C3, and B3 is a parent to C4 and C5. In addition, C4 is a parent to 
D1. 


Fraternal records are at the same level in the hierarchy; they can have the same parent or 
no parent. Thus, defined records Al and A2 are fraternal; B1, B2, and B3 are fraternal; 
C1, C2, and C3 are fraternal; and C4 and C5 are fraternal. However, C1, C2, and C3 are 
not fraternal to C4 and C5 because they have a different parent. 


In practice, most defined files contain few types of defined records. This example contains 
many for illustration. 


Parent, child, and fraternal records must be defined in a prescribed order in the data 
definition and appear in that order in the defined file. A parent record is defined first, 
followed by each of the child records belonging to that parent. Each of these child records 
is followed by any child record to which it is a parent. Figures 2-6 and 2-7 show the order 


in which the defined records of the hierarchy shown in Figure 2-5 are defined. Figure 2-6 
also illustrates the parent-child relationships in the defined file, and Figure 2-7 shows the 


fraternal relationships. 
a eo 


Figure 2—5. Hierarchical Structure of a Defined File 
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Figure 2—6. Parent/Child Relationships in a Defined File 





Figure 2—7. Fraternal Relationships in a Defined File 


2.2.2. Defined Records 


Defined records constitute the defined file. They contain the specific data needed by a 
particular application. You describe your defined records to the data definition processor, 
which processes the description for use by online IMS 90. In turn, DRM constructs the 
defined records and passes them to the action program or UNIQUE. DRM constructs the 
defined record containing record items in the same order specified in your defined record 
description. 


Each defined record contains a record identifier. Similar to data management's use of 
ISAM keys to locate records, DRM uses the record identifiers to build keys that it passes to 
data management. Data management then uses these keys to extract data from the user 
logical data file. 
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The programmer describing his defined record to the data definition processor may specify @ 
a new item name on the IDENTIFIER statement of the item definition. He also specifies the 

name of the logical record from which the identifier item is being extracted. Figure 2-8 

shows the derivation of the identifier from the logical record. 


USER LOGICAL RECORD 





ST-CODE STATE 


STATE-NAME 





DEFINED RECORD 


Figure 2—8. Defined Record Identifier Redefined from User Logical Record 


The identifier item names appear on the terminal as column headers to the terminal 6 
operator using UNIQUE. Figure 2-9 illustrates a column header on the terminal display 
screen. (Column headers are normally followed by data as shown in Figure 2-11.) 


“STATE-NAME 


Figure 2—9. Terminal Display of Defined Record Identifier as Column Header 


Each defined record can have only one identifier, which may have up to 39 items. To the 
action programmer, a defined record identifier consists of the first few items of the defined 
record; however, these identifier items can come from any data field of the logical record 
that is part of the key. Identifier items are arranged from left to right in major-to-minor 
order. Because identifier items are derived from key fields, only records in an indexed file 
or a data base subschema can supply these identifier items. Additional data items in a 
defined record are derived from the same record that supplies the identifier or from other 
records in conventional files or a subschema by defining supp/ements to the data 
definition. (See 2.3.7.) Nonindexed files may be used as a source for defined records only 

in combination with indexed files or subschemas. Defined record supplements may name ® 
a key or need not name a key. Thus, they may be derived from indexed or nonindexed 
files. 
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The identifier associated with the defined record is used by DRM to access that record. 


Figure 2-10 illustrates the derivation of a defined record identifier from one logical record 
in a simple defined file. 


USER LOGICAL RECORD 





Record Key 


IDENTIFIER STATE-NAME FROM STATE 
IDENTIFIER CITY-NAME FROM CITY 


DEFINED RECORD 


DEFINED RECORD SUPPLEMENT FROM 
IDENTIFIER 


ANOTHER LOGICAL 
RECORD 








Figure 2—10. Defined Record Identifier in a Simple Defined File 


Figure 2-11 illustrates a defined record with item names used as column headers plus 
data comprising the defined record. 


*STATE-NAME CITY-NAME 
. ALABAMA HUNTSVILLE 





Figure 2—11. Terminal Display of Column Headers and Data Items 


A hierarchical defined file contains two or more types of defined records that are related to 
each other in a parent/child relationship. Several occurrences of the child-type record are 
associated with each occurrence of the parent-type record. 


The child record identifier is always longer than the parent record identifier because the 
entire value of the parent identifier is repeated at the beginning of the child identifier 
associated with that parent record. Hence, when listed at the terminal, those child records 
appear in order immediately following the parent record. 
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Additional items used in a child record identifier distinguish one child record occurrence 
from another. Note that the portion of the child identifier that is unique to each child 
record occurrence may come from a different file than the file that provided the parent 
record identifier. Figure 2-12 compares the parent and child record identifiers in a 
hierarchical defined file and shows their derivation from logical records in two different 
indexed files. 


Figure 2-13 shows the terminal display of parent/child defined record identifiers in 
response to a request for the parent record or the child record. (See also Figure 2-32.) 


indexed Files 








STATE-REC Logical Record E-CY-REC Logical Record 
LS ooo 
Key Key 
IDENTIFIER STATE FROM STATE-NAME 
ITEM CAPITAL 
IDENTIFIER CITY FROM CITY-NAME 
ITEM POPULATION FROM CITY-POP 
Defined File 
Parent 
Record Identifier 
r——— 









Parent 


Record CAPITAL 


Child 


Raeced POPULATION 


ay, 


Child Record Identifier 


Figure 2—12. Parent/Child Defined Record Identifiers 
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DISPLAY ALABAMA 
STATE CAPITAL 


ALABAMA BIRMINGHAM 





a. Parent record displayed 


DISPLAY ALABAMA, BIRMINGHAM 
CITY : POPULATION 


ALABAMA, BIRMINGHAM 325,000 





b. Child record displayed 


Figure 2—13. Terminal Displays of Column Headers and Data ltems for Parent and Child Records 


2.3. DATA DEFINITION LANGUAGE > 


The data definition language is a COBOL-like language used to describe the defined files 
accessed by user action programs or UNIQUE through defined record management. Each 
data definition describes one defined file in terms of one or more logical files. These may 
be indexed files or a combination of indexed and nonindexed files. You can also use a 
DMS 90 data base subschema as a source in a data definition. The data definition 
language for a data definition that uses subschema records as source differs from that 
described here. The syntax for such a data definition is documented in the IMS 90/DMS 
90 interface user guide/programmer reference, UP-8748 (current version). Any number of 
defined files can be created through multiple runs of the data definition processor. 


2.3.1. Format Presentation and Coding Rules 


In addition to the statement conventions presented in Appendix A, the following rules 
apply to the presentation of formats in this section and the coding of input for the data 
definition processor. | 


1. Underlined lowercase terms, such as record-description and defined-record-definition, 
are names of formats detailed in subsequent illustrations. 
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2. Uppercase words are all reserved words. 


= @=€AIll underlined uppercase words are required when the statements or clauses of 
which they are a part are used. 


= Uppercase words that are not underlined are optional, i.e., they may or may not 
be coded in the source program. 


= Uppercase words, whether underlined or not, must be spelled exactly as in the 
format. 


3. A user-supplied word can be any sequence of not more than 30 characters, except for 
reserved words. Each character is taken from the set A through Z, O through 9, and 
the hyphen (-). The hyphen may not appear as the first or last character in a word. 


4. User words are represented in the formats by generic terms where they are initially 
defined and also where they refer to previously defined user words. All references are 
in the backward direction; the definition always precedes the references. 


5. Alphabetic and alphanumeric literals must be enclosed by single quotes to distinguish 
them from user words. Numeric literals are not enclosed by quotes. 


6. Record definitions, and item definitions within them, are described in a defined file 
definition in exactly the same order as the logical data they represent appear in the 
defined file. 


7. The standard COBOL coding form should be used for coding the data definition 
processor input. Certain statements must begin in margin A, as noted in the 
descriptions of those statements later in this section. Margin A is column 8 of the 
coding form. All other statements must begin at column 12 (margin B) or beyond. 


8. Statements in the identification division and the data division are followed by periods. 
Periods and semicolons are optional throughout the defined file definition and are 
ignored by the data definition processor. 
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A list of reserved words that must not be used as user words in the definition division of 
the input to the data definition processor is presented in Table 2-1. Except for the words 
DEFINITION and DIVISION, these reserved words may be used in the data division. The 
COBOL reserved word list documented in the OS/3 extended COBOL supplementary 
reference, UP-8059 (current version) and OS/3 American National Standard COBOL 
programmer reference, UP-8613 (current version) applies to the data division of the data 


definition. 


AS 
ASSUME 
ASSUMES 
BREAK 

BY 

CALC 
CHANGE 
CONTAINS 
CONTROL 


CONTROLLED 


CONTROLLING 


COUNT 


Table 2—1. Data Definition Reserved Words 


DBS 


DEFINED 


DEFINITION 


DELETE 


DIVISION 


DMS 


DUPLICATE 


FILE 


FILL 


FOLLOWS 


FROM 


GROUP 


HIDDEN 


IDENTIFIER 


KEY-NAME 


MANUAL 


MUST 


NAME 


NEUTRAL 


NEXT-MEMBER- 
POINTER 


OF 


ONLY 


OWNED 


OWNING 


PARENT 


PASSWORD 


PERIOD 


POINTER 


PREFIX 


RECORD 


REPEATING 





ROLE 


SELECTIVE 


SEMICOLON 


SET 


SUBFILE 


SUBRECORD 


SUPPLEMENT 


THROUGH 


THRU 


TO 


TOTAL 


TYPE 


UPDATE 


USING 


VALUE 


VALUES 


VIA 


WITHIN 
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2.3.2. Data Definition Structure © 


A data definition contains three divisions: the identification division, the data division, and 
the definition division. The identification division and the data division are intentionally 
similar to the COBOL identification and data divisions. The definition division is unique to 
IMS 90. The data division is used for describing the logical files from which the defined 
file is to be extracted; the definition division describes the defined file. 


Figure 2-14 illustrates the overall structure of the data definition. The record-description 
and defined-file-definition entries are names of group formats that are expanded in 
Figures 2-15 and 2-16. 


IDENTIFICATION DIVISION. 
PROGRAM-1D.data-definition-name. 
[AUTHOR.comment-entry. ] 

[ INSTALLATION. comment-entry. } 
[DATE-WRITTEN.comment-entry. ] 
[DATE-COMPILED.comment-entry. ] 
[SECURITY.comment-entry. ] 
[REMARKS .comment-entry. ] 


DATA DIVISION. _ 


FILE SECTION. 


FD file-name-1l.record-description [record-description]... 
[FD file-name-2.record-description [record-description]...]... 


DEFINITION DIVISION. 


defined-file-definition 





Figure 2—14. Overall Format of a Data Definition 


2.3.2.1. Identification Division 


The identification division must begin with the reserved words IDENTIFICATION DIVISION 
followed by a period and spaces to column 72. The PROGRAM.-ID statement specifies the 
data definition name that appears on the diagnostic listing and serves to identify the 
contents of the listing. A data-definition-name is required on the PROGRAM.-ID statement 
following the division header. The data-definition-name must be alphanumeric and begin 
with an alphabetic character. Although you may use more characters in the data- 
definition-name, the system uses only the first six characters to identify the object 
program on the compiler listing. Therefore, it is difficult to identify your programs when 
the first six characters are not unique. The first six characters of each data-definition- 
name within a given program library must be unique only to produce a unique object 
module. Each statement must begin in margin A (column 8) of the coding form. Each 
optional comment entry can contain any printable characters. If it exceeds a single line, 
additional lines must begin beyond column 11 in the coding form. 
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2.3.2.2. Data Division 


The data division contains only a file section, in which the user logical files are described. 
It is similar to the standard COBOL file section, except that it cannot contain the VALUE 
clause. Other clauses are the same as in the OS/3 implementation of American National 
Standard COBOL, X3.4—1968. 


You may specify multiple logical files, each containing multiple logical record descriptions. 


The data division must begin with the reserved words DATA DIVISION followed by a period 
and spaces to column 72. DATA DIVISION, FILE SECTION, FD statements, and 01 level 
record descriptions must begin in margin A. All other entries must begin beyond column 
11. The expressions filename-1, filename-2, etc, may be one to seven alphanumeric 
characters in length and must begin beyond column 11. The same file names must be 
specified by filename positional parameters in the configurator FILE section. 


The record-description specification is illustrated and discussed in 2.3.3. 


2.3.2.3. Definition Division 


The definition division, unique to the data definition language, describes the defined file by 
designating a defined file name and describing each defined record, item, supplement, 
subrecord, subitem, and subfile. 


The definition division must begin in margin A with the reserved words DEFINITION 
DIVISION followed by a period and Spaces to column 72. 


The defined-file-definition is described in 23.4 


2.3.3. Logical Data Record Description 


The logical records that constitute conventional files from which the defined file is 
extracted are described in FD statements in the file section of the data division. (See 
Figure 2-14.) Nonindexed files can be used as source in a data division only in 
combination with indexed files. 


Figure 2-15 illustrates the two formats that can be used to describe user logical records. 
The formats are intentionally similar to record descriptions in a COBOL data division. The 
first format copies data descriptions from an existing library; the second format describes 
the logical record items from which the defined records will be formed. 
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Format 1: 


Ol data-name-1; COPY Jibrary-name 


| REPLACING word-1 BY (word-2 
| = rdentitier-1] 
literal-1l 
| , word-3 BY {word-4 
| SS [Téentitier-2]] | 
literal-2 ee 


Format 2: 


level-number{data-n 
FILLER 
EFINES data-name- 3] 

NK WHEN ZERO] 


7 BeH 
Ue 


{BiG is eee ume | 
E 


Ea TO integer-2 TIMES [DEPENDING ON data-name-4)} 


‘alee 


~ |x 
oe na 
- |o 








integer-2 TIMES 


ASCENDING \KEY 1S data-name- ee name -6]... | 
DESCENDING 
N 


DEXED BY index-name- 1 [vir index-name-2]... | 
: { SYNC LEFT 
NCHRONIZED f \RIGHT 
; MAP 


1S integer-3 CHARACTERS] 


a 


SIGN is] {LEADING | SEPARATE SNBRAC TER 
TRAILING 


; [USAGE 1S] / COMP | 
COMPUTATIONAL 





COMP - 3 

COMP -4 
COMPUTATIONAL - 3 
COMPUTATIONAL -4 
DISPLAY 

INDEX — 





Figure 2—-15. Logical Record Description Formats 
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2.3.4. Defined File Definition 


The defined file definition contains the defined record; item; and optional supplement, 
subrecord,and subfile definitions that IMS 90 uses to construct the defined file from user 
logical data files (Figure 2-16). The defined file definition is coded in the definition 
division. IMS 90 requires that only one defined file be included in a data definition. 


In the consolidated format for the defined file definition illustrated in Figure 2-16, 
statements enclosed in solid-line rectangles are required in a data definition, and 
statements enclosed in broken-line rectangles optionally can be included. Solid-line 
rectangles within broken-line rectangles indicate that the statements in the inner 
rectangle must be included if the statement in the outer rectangle is included. 


The rectangles within rectangles illustrate a nested structure, with the defined record and 
subfile definitions subordinate to the DEFINED FILE definition and the item, supplement, 
and subrecord definitions subordinate to the defined record definition. (See also Figure 
2-17.) All subordinate definitions can be used repeatedly within the larger definitions. 


Periods and semicolons are optional throughout the defined file definition. The statements 
in each box of Figure 2-16 are described in 2.3.4.1 through 2.3.10.2. 


2.3.4.1. DEFINED FILE Statement 


The DEFINED FILE statement indicates the beginning of a defined file definition and 
supplies a name for future reference in password definition records and action programs. 
The DEFINED FILE statement must begin in margin A and be the first statement in the 
definition division. 


Format: 


DEFINED FILE defined-file-name[{ PASSWORD] 


where: 


defined-file-name 
Names the defined file and must be one to seven characters in length. The name 
must be different from that of any logical file assigned to IMS 90. The data 
definition processor truncates a defined-file-name longer than 7 characters and 
uses the first seven characters for the defined-file-name. There is no error 
message when truncation occurs. 


PASSWORD 
Specifies that defined-file-name is to be used by terminal operators as the 
password in the UNIQUE OPEN command to gain access to this defined file. If 
PASSWORD is omitted, terminal operators using UNIQUE can access the defined 
file only if a password is defined by means of the NAMERES file utility. 


Note that multiple passwords may be used to access a defined file and that a 
password defined by means of the NAMEREC utility does not negate a password 
defined in the data definition unless the passwords are the same. If access to the 
defined file is to be limited to specific terminals, the PASSWORD option should 
be omitted and the NAMEREC utility should be used. | 
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DEFINED FILE defined-file-name { PASSWORD] 
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DEFINED RECORD defined-record-name-1 





FROM stored-record-name-1 
FROM CONTROL BREAK IN stored-record-name-2 
FROM REPEATING GROUP data-name-1 
[TYPE tS literat-1 } 
[PARENT 1S defined-record-name-2] 
[PREFIX 1S literal-2 ] 
POINTER IS item-name-1[.item-name- 2] 
frost defined-record-name-3 1 
supplement-name- 1 
[FILL KEY TO Jliteral-3 | 


fTaicow (apo OF RECORD 
DELETE 
ADD AWD DELETE 











IDENTIFIER [item-name-1 
{itt {1 


eee aa) 


tem-name-2 ata-name-2 








[HIDDEN] 
{MUST ADD| 
[ALLOW CHANGE] 


VALUE 15 literal-1i1] JTHROUGH literal-2 fiteral-3. THROUGH? Ii 
VALUES ARE THRU THRU 





SUPPLEMENT supplement-name-l 


| FROM stored-record-name-1 

| FROM REPEATING GROUP data-name-1 

| [POINTER IS item-name-1 [,.item-name-2]...]} 

[FILL KEY TO jJiteral-1 | 

‘Soe eset ROLE IN UPDATE 
CONTROLLED 

| : iTEM [item-name-2 FROM] data-name-2 

| [Hi ODEN} 

| (MUST ADD] 

| | ALLOW CHANGE} 

| VALUE 15 literalt-1 THROUGH literal-2]). literal 

| VALUES ARE THRU 





item-alias-1 FROM] item-name- 3 
item-alias-2 FROM] item-name-4}... |] 


| 
= 


o 
Leal 
\— 
rn 
— 
aa] 





ADD AND ee ea 
ITEM {item-alias-1 ee ee | 


ttem-alias-2 


[ALLOW CHANGE | 


VALUE IS literal-1 THROUGH J literal -2 Piteral -3 
VALUES ARE THRU 


| 
| 
| 
| 
| eo : 
| [MUST AOD] 
| 
| 
| 
| 
| 





| SUBFILE subfile-name-1 [ PASSWORD} 


CONTAINS Jdefined-record-name-l jpdefined-record-aame-2 £uG 3 
subrecord-name-l subrecord-name-?2 


|e 


-3 |] }THROUGH{ literal-4 sh 
[4 ties \ J] 


THROUGH literai-4 tea he 
pegguanyr tere] 


Figure 2—16. Consolidated Format of Defined File Definition 
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@ Programming Note: 


The defined file name also is used to create a record key for the data definition 
record. Other references to defined file names and subfile names outside the oa 
definition itself include: 


= keyword sapanneiers DFILE and DDRECORD*® in the ACTION section of the 
configuration; 


= keyword parameters FN and DDN* in the password definition input to the 
NAMEREC file utility; 


w the defined-file-name parameter in action program function calls to defined 
record management; | 


= the DEFINED-FILE-NAME and DATA-DEF-REC-NAME* fields in the program 
information block for COBOL action programs; and 


=» the ZA#PDFN and ZA#PDDRN*® labels in the program information block DSECT 
for BAL action programs. | 





Examples: 
8 12 
& 1. |] DEFINED FILE PAYROLL PASSWORD 


2.{ FELE PAYROLL PASSWORD 
3.] FILE PAYROLL 


Examples 1 and 2 perform exactly the same function. The word DEFINED can be 
omitted because it is not underlined in the format. The defined file name is PAYROLL, 
and the password used to access the file via UNIQUE also is PAYROLL. 


In example 3, PASSWORD is omitted, precluding access to the file by a terminal 


operator using UNIQUE. Either a password is generated by the NAMEREC utility or 
the defined file is accessed only by user action programs, not UNIQUE. 


*These can be defined file names but not subfile names. 
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2.3.5. Defined Record Definition © 


The defined record definition describes the source and contents of each defined record and 
the allowable operations. Figure 2-17 illustrates the format of the defined record 
definition. The underlined lowercase terms (item-definition, supplement-definition, and 
subrecord-definition) are names of group formats that are described in separate 
subsections. Items appear in the defined record in the same order that their item 
definitions appear in the defined record definition. 


DEFINED RECORD defined-record-name- 1 
FROM stored-record-name-1 
FROM CONTROL BREAK IN stored-record-name-2 
FROM REPEATING GROUP data-name-1 
[TYPE iS literal-1] 
[PARENT : defined-record-name- 2} 
[PREFIX literal-2] | 
i item- ee 
FOLLOWS {defined-record Puli 
eee name-1l 
[FILL KEY TO literal-3] 


ALLOW ADD OF RECORD 
DELETE - 
ADD AND DELETE | & 
item-definition [item-definition]... 
[supplement-definition]... 
[ALSO [item-alias-1 FROM] item-name-3 
[,[item-alias-2 EROM] item-name-4]... 


fsubrecord-definition]... 





Figure 2—17. Defined Record Definition Format 


2.3.5.1. DEFINED RECORD Statement 


The DEFINED RECORD statement indicates the beginning of a defined record definition 
and assigns a name to the record being defined. It must be the first statement following 
the DEFINED FILE statement or another defined record definition and must begin in 
margin A of the coding form (column 8). 


Format: 


DEFINED RECORD defined-record-name-1 


where: 


defined-record-name-1 @ 


Is a 1- to 30-character name, unique within the data definition, that identifies 
the defined record. 
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© Examples: 


8 12 

1. | DEFINED RECORD EMPLOYEE 

2. | RECORD EMPLOYEE 
Again, both examples are the same; DEFINED is omitted in the second example 
because it is not required in the format. The first defined record in the defined file, 
PAYROLL, is named EMPLOYEE. If record types other than EMPLOYEE records exist 
in the defined file, one or more additional DEFINED RECORD statements must be 
coded in the definition division. 

Programming Note: 


IMS 90 accepts a maximum of 78 ITEM and IDENTIFIER statements for each defined 
record. 


2.3.5.2. FROM Statement 

The FROM statement identifies the logical record that Supplies the primary part of this 
defined record. The logical record supplying the primary part must be from an indexed file. 
The primary part of a defined record contains the record identifier (ISAM or MIRAM key) 
and any items coming from the same logical record. 


Format: 


FROM stored-record-name-1 


where: 


stored-record-name-1 
Refers to an 01 level entry in the file section of the data division. 


Programming Notes: 


1. The FROM statement must be the first statement following the DEFINED 
RECORD statement. | 


2. Stored-record-name-1 must be a unique name or be fully qualified. (Rules for a 
fully qualified name are the same as for a COBOL fully qualified name.) 


3. Any item within stored-record-name-1 may be included in the primary part of 
this defined record if: 


7 it meets constraints on length and usage (see 2.3.6.2); and 


# its position within stored-record-name-1 comes before any item defined with 
& an OCCURS clause. 
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Example: 


8 12 


~ DEFINED RECORD EMPLOYEE FROM EMPLOYEE-REC 


In this example, the primary part of the defined record EMPLOYEE will be supplied by 
the logical record EMPLOYEE-REC, which is an 01 level entry in the file section of the 
data division of this data definition. 


2.3.5.3. FROM CONTROL BREAK Statement 


The FROM CONTROL BREAK statement specifies that the primary part of this defined 
record comes from the first of a sequence of logical records, all of which contain the same 
value in the leftmost characters of their record keys. In other words, the primary part of 
the defined record consists of the identifier only. The typical use of the FROM CONTROL 
BREAK statement is to access a specified portion of a defined file using, for example, the 
FOR parameter of a UNIQUE LIST or DETAIL command. The FROM CONTROL BREAK 
statement also can enable UNIQUE statistical functions to provide subtotals for subsets of 
child defined records associated with occurrences of the control break. 


Format: 


FROM CONTROL BREAK IN stored-record-name-2 


where: 


stored-record-name-2 
Refers to an O01 level entry in the file section of the data division. The source 
record must be from an indexed file. When necessary to avoid ambiguity, stored- 
record-name-2 must be fully qualified. 


As indexed records are read sequentially, a new occurrence of the current defined record 
is generated each time a new value appears in those left-hand character positions of the 
logical record key that contributes this defined record’s identifier. Typically, the indexed 
record that contains the identifier value (and is therefore the source of the current defined 
record) also will be the source of the next occurrence of the first subordinate defined 
record. 


Programming Notes: 


1. The FROM CONTROL BREAK statement must be the first statement following the 
DEFINED RECORD statement. 


2. The current defined record must be named subsequently as the parent of at least 
One subordinate record. The first subordinate defined record must name stored- 
record-name-2 as its source in a FROM statement or another FROM CONTROL 
BREAK statement. 
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© Examples: 


8 12 
1. | DEFINED RECORD EMPLOYEE 
FROM CONTROL BREAK IN EMPLOYEE-REC 
2. | RECORD EMPLOYEE FROM BREAK EMPLOYEE-REC 


Example 1 uses the long form of both the DEFINED RECORD and FROM CONTROL 
BREAK statements; example 2 illustrates the short form, using only the underlined 
reserved words in the format. Both perform the same function. | 


The defined record named EMPLOYEE will receive only an identifier from the logical 
record, EMPLOYEE-REC, which is a 01 level entry in the data division file section of 
this data definition. 

2.3.5.4. FROM REPEATING GROUP Statement 

The FROM REPEATING GROUP statement specifies the group item, described in the data 


division with an OCCURS clause, that supplies the primary part of this defined record. This 
statement must immediately follow the DEFINED RECORD statement. .. 


Format: 


& FROM REPEATING GROUP data-name-1 | 


where: 


data-name-l 
Refers to a data name defined in the data division with both an OCCURS clause 
and a KEY clause. When necessary to avoid ambiguity, data-name-7 must be 
fully qualified. 


Programming Notes: 
1. The logical record that contains data-name-1 must not be created by a 
UNIQUE ADD command or a defined file INSERT function; otherwise, the 


value of data-name-1 is binary zeros and, therefore, cannot contain a unique 
key. 


2. Any item within data-name-?7 may be included in the primary part of this 
defined record if: 


= it meets constraints of length and usage (see 2.3.6.2); and 


a its position within data-name-7 precedes any item (other than data- 
name-7 itself) defined as an OCCURS clause. 
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Example: 


8 12 


RECORD DEPENDENTS FROM GROUP DEPENDENT-REC 


In this example, the primary part of the defined record DEPENDENTS is supplied by 
the repeating group item DEPENDENT-REC, which is an O02 level entry in the logical 
record EMPLOYEE-REC. (See example in 2.3.5.2.) IMS 90 requires that the item 
DEPENDENT-REC be described in the data division file section with both an OCCURS 
clause and a KEY clause. For example: 


8 12 
82 DEPENDENT-REC OCCURS 5 TIMES 


ASCENDING KEY [|S DEP-NAME 
83 DEP-NAME PIC X(15) 


2.3.5.5. TYPE Statement 

The TYPE statement provides user-written action programs with an indicator identifying 
the record type delivered as a result of a SETL and sequential GET function. The type 
indicator is presented in the detailed status code of the program information block (PIB). 


This statement is applicable only when there is more than one record type in a given 
defined file and the file is being accessed by user action programs. 


Format: 


TYPE IS titeral-1 


where: 
literal-l 
ls a single alphanumeric character. It is the actual value that is delivered in the 
DETAILED-STATUS-CODE field in the PIB. Each defined record type must be 
assigned a unique character identification. 
Example: 
8 12 


TYPE IS ‘A’ 
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2.3.5.6. PARENT Statement 


The PARENT statement establishes the relationship of a defined record to other defined 
records in the hierarchical organization of the defined file. A defined record definition must 
always contain a PARENT statement unless the record being defined is at the highest level 
in the hierarchy. : 


Format: 


PARENT IS defined-record-name-2 


where: 


defined-record-name-2 
Refers to a defined record previously described in this data definition. It must 
have been defined in the immediately preceding defined record definition or be 
one of the direct ancestors of the immediately preceding defined record. 


The position of defined records in the defined file reflects the order of their defined record 
definitions within the defined file definition. 


The first defined record definition never contains a PARENT statement. It is at the highest 
level in the hierarchy and, therefore, cannot be subordinate to a parent-type record. If a 
subsequent defined record definition does not contain a PARENT statement, that defined 
record also is considered to be at the highest level in a hierarchy. All record types that 
have no parents are considered to be fraternal. 


More than one defined record definition can name the same parent. Following each 
definition of a parent record, defined records subordinate to the parent record and 
fraternal to each other are defined. 


Programming Notes: 


A defined record can be named as the parent of another defined record only if one of 
four relationships exists between their sources in the logical records read from disk: 


1. The source of the child record is a repeating group item occurring within the 
group that is the source of the parent or one of the parent’s supplements. (See 
Figure 2-31.) | 


2. The sources of the parent record (or one of the parent’s supplements) and the 
child are two distinct record types (01 level entries) that exist, collated, in the 
same indexed file. (See Figure 2-29.) 


3. The source of the parent record is a control break that is detected while reading | 
the source of the child record. 
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4. The source of the child record is a sequence of indexed records that exist © 
somewhere entirely remote from the source of the parent or any of its 
supplements. In this case, IMS 90 requires a POINTER statement in the defined 
record definition for the child record. (See Figure 2-32.) | 


Example: 


8 12 


PARENT !S EMPLOYEE 


In this example, the parent of the child record being defined is the previously defined 
record EMPLOYEE. 


2.3.5.7. PREFIX Statement 


The PREFIX statement inserts an additional character or characters that are not present in 
any physical record into the identifier of a defined record, thus enabling identifier values to 
reflect the order of accessing or listing fraternal record types. Either the PREFIX statement 
or the VALUE statement (or both) must be included for each defined record that is 
fraternal to another defined record. The PREFIX statement must be used if the range of 
values for the identifier items of fraternal record types overlap. This can be the case if the 
records have sources in different files or in different repeating group items. — 


Format: ae: SO @ 
PREFIX IS literal-2 


where: 


literal-2 
Is a constant inserted into the identifier of a fraternal-type record and must be 
enclosed by single quotes. 


Programming Notes: 


1. The values of successively defined prefixes for fraternal record types must be in 
ascending order and must also be the same length. 


2. The prefix defined by this statement appears in the identifier, as seen by the 
action program and the terminal operator, of every occurrence of this defined 
record. It immediately precedes the identifier item defined in the first item 
definition for this defined record. 


Example: 


8 12 


PREFIX IS ‘A’ ¢ 
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In this example, assume that the defined file PAYROLL contains three types of 
records: EMPLOYEE, DEPENDENTS, and PAYDATA, with EMPLOYEE being the parent 
of both DEPENDENTS and PAYDATA, and DEPENDENTS and PAYDATA being 
fraternal records. When listing or accessing the file sequentially, all DEPENDENTS 

_child-type records for an EMPLOYEE parent-type record are delivered before any 
PAYDATA records. Prefixes are identified as ‘A’ for DEPENDENTS records and ‘B’ for 
PAYDATA records. Because A comes before B alphabetically, and DEPENDENTS 
records occur before PAYDATA records in the defined file, the prefixes support the 
requirement that Successive occurrences of defined records always contain identifiers 
with ascending values. 


2.3.5.8. POINTER Statement 


The POINTER statement defines the leftmost characters of the search key for the source of 
the defined record’s primary part. The POINTER statement is used only if there is a 
PARENT statement for this defined record and the source of the primary part of this 
defined record and its parent exist in different files or at randomly different locations 
within the same file. 


Format: 


POINTER IS ittem-name-1 [,item-name-2]_ 


where: 


item-name 
Has been defined in a direct ancestor of this. defined record. 


To retrieve the primary part of this defined record, IMS 90 concatenates the values of 
item-name-1, ittem-name-2... to form a character string. Then: 


1. if the source of this defined record’s primary part is an indexed record, that character fe 
string comprises the characters to the left of the identifier items in the record key; 
and 


2. if the source is a repeating group item, then the leftmost characters of the character 
string are used to locate the occurrence of the record that contains the source. If this 
repeating group item is nested within a larger one, additional characters will be in the 
pointer and will be used to locate the larger group item by its key. 


Example: 


8 12 


POINTER IS EMP-NR 


In this example, assume that the parent record is EMPLOYEE and you are defining a 

child record called DEPENDENTS. The source of the primary part of DEPENDENTS is <_ 
an indexed file ordered by employee number and dependent:-name. The item EMP-NR 

of EMPLOYEE contains the employee number that points to the appropriate 
dependent records and is used to position the dependent’s file. 


ep 
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2.3.5.9. FOLLOWS Statement 


The FOLLOWS statement specifies that the source of this defined record is to be read 
sequentially following the source of a previously defined primary part or supplement in the 


> same indexed file. It is required only if the source of the defined record does not follow the 
source most recently mentioned in a defined record definition or supplement definition 
=e involving the same indexed file. | 
Format: 
POR LOWS {Cet raed: record: name 3} 
supplement -name- Il 
where: 
defined-record-name- 3 
Identifies a previous defined record so that the source of the primary part of the 
current defined record sequentially follows the source of the primary part of that 
defined record. 
supplement-name- 1 
Identifies a previous supplement so that the source of the primary part of the 
current defined record sequentially follows the source of that supplement. 
Programming Notes: © 
1. This statement never appears in the first defined record definition for a defined 
file or when the source of the defined record is a repeating group item. 
> 2. This statement is used only if the source of the defined record is an indexed file 
already named as a source in a previous defined record definition or supplement 
definition. 
Example: 


8 12 


FOLLOWS BRAND-RCD 


In this example, assume that a liquor wholesale application has a logical ISAM file 
containing two types of user logical records: brand records and stock records. The file 
layout is a brand record followed by corresponding stock records. The stock records 
are the inventory record by unit of issue (i.e., pint, fifth, etc). 


A defined record named BRAND-RCD has an item named SUBSTITUTE, which is a 

pointer to a supplement (i.e., the brand record “JIM BEAM” could have as a 

substitute ““OLD CROW”). Another defined record named STOCK-RCD is defined after 
-BRAND-RCD. Its definition uses the statement in this example to indicate that IMS 90 = 
should read logical file stock records that follow the “JIM BEAM” record, rather than © 
the logical file stock records that follow the ‘““OLD CROW” record. 
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2.3.5.10. FILL KEY Statement 


The FILL KEY statement specifies the rightmost characters of an indexed record key to 
differentiate between record types in an indexed logical file when they are identical for all 
records of the same type. 


Format: 


FELL KEY TO Jiteral-3 


where: 


fiteral-3 


Identifies the rightmost character or characters of the indexed file’s key and must 
be enclosed by single quotes. | _—_ 


Programming Notes: 


1. 


Example: 


8 


The FILL KEY statement is required only if the indexed file record key is longer 
than the combined length of the pointer items (if any) and the identifier items 
and if the remaining characters in the key are not all spaces (hexadecimal 40). 
When creating a search key, IMS 90 fills all remaining character positions with 
Spaces and then moves /itera/l-3, if specified, into the rightmost character 
positions of the record key. 


The length of literal-3 following the FILL KEY clause must not be longer than the 
part of the key not specified by IDENTIFIER or POINTER statements. 


Indexed records not previously mentioned in the data definition are permitted to 
intervene in the source sequence if the FILL KEY statement is present. 


12 


FILE KEY TO ‘E’ 


In this example, assume there are two types of records in an indexed file being used 


as a 


source of defined records: EMPLOYEE-REC and DEPENDENT-REC. The key to the 


employee records is xxxxE, and the key to the dependent records is xxxxn. By defining 
a record EMPLOYEE with the FILL KEY statement in this example, you can access the 
EMPLOYEE-REC records simply by specifying a key of XXXX. 
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2.3.5.11. ALLOW ADD AND DELETE Statement 


The ALLOW ADD AND DELETE statement permits the addition and/or deletion of 
occurrences of this defined record. This statement cannot be used if the FROM CONTROL 
BREAK or FROM REPEATING GROUP statement is included for this defined record. 


Format: 
‘ ALLOW (ADD © OF RECORD 
DELETE 
ADD AND DELETE 
NOTE: 


The absence of these statements in a record definition disables the corresponding ° 


functional capability. For example, if ALLOW ADD or ALLOW ADD AND DELETE is not 
specified in the EMPLOYEE record definition, any input of the UNIQUE ADD command or 
any action program issuance of the CALL INSERT function involving an EMPLOYEE record 
is rejected as invalid. 


Example: 


8 12 


ALLOW ADD AND DELETE 


This example allows the defined record EMPLOYEE (see example in 2.3.5.1) to be 
added to or deleted from the defined file. 


2.3.5.12. ALSO Statement 


The ALSO statement specifies that the defined record is to include copies of items 
described in definitions of its direct ancestors. Without the ALSO statement, these items 
can be included in the defined record only by defining a supplement (by means of the 
supplement definition) whose source is the same as the source of the direct ancestor 
record. Note that the ALSO statement must follow the item definition and any supplement 
definitions for this defined record. 


Format: 


ALSO [ITEM-alias-1 FROM] item-name-3 [,[item-ailtas-2 FROM] item-name-4] 


where: 


item-altas 
Specifies a unique name for an item within this defined file from 1 to 30 
characters in length. 


item-name 
Refers to an item defined in an item definition within a defined record definition 
for a direct ancestor of this defined record. 
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Example: 


8 12 


ALSO EMP-NAME FROM NAME 


In this example, the item EMP-NAME is included in the record being defined after the 
ancestor record item, NAME. | 


2.3.6. Item Definition 


The defined record consists of elements or items known by their item names. A separate 
item definition is required to describe each item name. Figure 2-18 shows the item 
definition format. | 


IMS 90 accepts a maximum of 78 ITEM and IDENTIFIER statements. If more:than 78 are 
processed, the data definition processor issues the following message: 


MAX TABLE AREA FOR ITEM STATUS IS 78. 


The data definition processor then terminates by indicating that it could not create the 
data definition record described. 


lf the items being defined are to be accessed via UNIQUE, it is important to consider 
carefully the size and meaning of the item names, because these item names are used as 
headings in all UNIQUE command response output. Indiscriminate assignment of item 
names can result in the inefficient use of CRT display screen space and erroneous 
interpretation of item contents. 


Note that when using UNIQUE, allow one extra byte for UNIQUE to insert a tab stop 
control character. 


IDENTIFIER [item-name- 1 aa tenant 
ITEM [item-name-2 data-name-2 


[HIDDEN] 
[MUST ADD] 
[ALLOW CHANGE] 


{VALne 1S literal-1 [{ PHROUGH Eaves 


VALUES ARE 


peer ay eet 


THRU 





Figure 2—18. Item Definition Format 
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IDENTIFIER Statement 


The IDENTIFIER statement indicates the beginning of an item definition and specifies the 


identifier for the defined record being described. 
Format: 

IDENTIFIER ii Geniaienced FROM] data-name-1 
where: 


ttem-name-] 


data 


Identifies the item, is 1 to 30 alphanumeric characters in length, and must be 
unique within the defined file definition. This name appears as a column header 
on the terminal when UNIQUE is used. , 


-name- ] 


_ Refers to a data name described in the data division as a part of the logical 


record or repeating group item that is the source of the primary part of this 
defined record. If the source of the primary part of this defined record is a logical 
record (either the FROM statement or the FROM CONTROL BREAK statement is 
employed), then data-name-1 must be part of the record key of that logical 
record. If the source is a repeating group item, data-name-1 must be part of the 
key of that item. 


Programming Notes: 


1. 


Example: 


8 


This 


lf 1tem-name-1 is identical to data-name-1, then item-name-7 and the word 
FROM can be omitted. 


Definitions of identifier items must precede those of all other items. 


If more than one IDENTIFIER statement is present, items must be defined in 
major-to-minor order. 


12 


IDENTIFIER EMP-NR FROM EMPL-NR 
IDENTIFIER EMP-NM FROM EMPL-NAME 


example illustrates the specification of multiple IDENTIFIER statements, the first 


indicating the major identifier, the second indicting a minor identifier. The value of 
the record key in the record that is the source of this defined record is: 


EMPL-NRAAAEMPL-NAMEAAAAAAAAAAA 
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© The sequence of items defined by the IDENTIFIER statement appears at the terminal 
as a String of variable-length items separated by commas: 


EMP-NR,EMP-NM 


When more than one IDENTIFIER statement is used, UNIQUE uses a single item name 
to refer to the entire identifier string. This item name is derived from the final 
IDENTIFIER statement. If the two defined items are individually named EMP-NR and 
EMP-NM, as in the example, then the item name for the combination, as seen by the 
terminal operator, is simply EMP-NM. 


2.3.6.2. ITEM Statement 


The ITEM statement indicates the beginning of an item definition and includes in the 
defined record an item described in the data division file section. 


Format: 


ITEM [item-name-2 FROM] data-name-2 


where: 


item-name -2 
© Identifies the item, may be 1 to 30 characters in length, and must be unique 
within the defined file definition. This name appears as a column header on the 
terminal when UNIQUE is used. 


data-name-2 
Refers to a data name described in the data division as a part of the logical 
record or repeating group item that is the source of the primary part or 
supplement of this defined record. Data-name-2 must never be qualified; 
qualification by the name of the source is always implied. 


Programming Notes: 


1. If item-name-2 is identical to data-name-2, item-name-2 and the word FROM 
may be omitted. 


2. The item named in this statement should not exceed 72 bytes. Moreover, it 
should not exceed line length minus 2 if UNIQUE is to display this item at any 
terminal whose line length is shorter than 74 characters. 


3. Defined record management moves the values of items to a new or updated 
source record in the order in which they are defined. If data-name-2 overlaps the 
source of another item (either item is a group item that contains the other), then 

the second item moved covers up the first. Therefore, if either item is to be 
changed, that item must be defined after the other item. 
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The data definition language permits a single item value on disk to be the source 
of two items within the same defined record. If you attempt to update those 
items to different new values, the resulting value on disk is unpredictable. 


Data-name-2 must be one of the following: 


s an elementary item with a USAGE clause value other than COMP-1 or 
COMP-2; or 7 | 


= agroup item that can be treated as if it were an elementary alphanumeric item; 


i.e., it contains only alphabetic, alphanumeric, or unsigned numeric ttems 
whose usage is DISPLAY. 


12 


ITEM EMP-NAME FROM NAME 
ITEM AGE 


items NAME and AGE from the current logical record are included in the defined 


record being described. The item NAME is assigned the name EMP-NAME, and the 


item 


2.3.6.3. 


age retains the name AGE. 


HIDDEN Option 


The HIDDEN option prevents the data item defined by the ITEM statement from being 
displayed at the terminal in response to a UNIQUE command. The purpose of this option is 
to allow a subsequent POINTER statement to refer to the item without allowing that item 
to be displayed. The HIDDEN option has no effect on a defined record accessed by user- 
written action programs. 


Another use of the HIDDEN clause assures the validity of a numeric field in a logical 
record on which another program may later want to perform arithmetic. When you add a 
defined record that does not include all fields in a logical record, binary zeros are inserted 
in the missing fields. To avoid this problem, include the field in the defined record with an 
ITEM statement and restrict its use with the HIDDEN clause. 


Format: 


HIDDEN 


Programming Notes: 


1. 


If the current item definition begins with an IDENTIFIER statement, the 
specification of the HIDDEN option is ignored. | 
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2. When a terminal operator using UNIQUE adds a defined record having an item 
definition for which the HIDDEN option is specified, IMS 90 automatically inserts 
spaces or zeros in the corresponding item of the record on disk. If the item is 
defined as alphanumeric, IMS 90 inserts spaces; if numeric, IMS 90 inserts zeros 
in the data format appropriate to the declared usage of the item. 


Example: 


8 12 


ITEM DEP-KEY HIDDEN 


Assume that DEP-KEY is a pointer to the supplemental dependent record in a 
nonindexed file. There would be no value in displaying this data at a terminal. 


2.3.6.4. MUST ADD Option 


The MUST ADD option specifies that this item must be present and contain a valid value 
for a record to be added to the defined file by the terminal operator. If defined as numeric, 
the item must be nonzero; if alphanumeric, it must contain other than all spaces. 


Format: 


MUST ADD 


Programming Notes: 


1. This option has meaning only in item definitions that begin with the ITEM 
statement; identifier items always must be present to add a defined record. 


2. If this item is in a supplement, the ROLE IN UPDATE for that supplement should 
be CONTROLLED. 


3. This option is inoperative unless the ALLOW ADD statement is specified in the 
defined record definition. 


Example: 
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1TEM EMP-NAME MUST ADD 


Before an EMPLOYEE record (see example in 2.3.5.1) can be added to the defined file, 
the item EMP-NAME must contain a valid value. Obviously, an employee record 
would be of little value without an employee name. Probably an item called AGE 
would not have the MUST ADD option because the item ts not critical to the record's 
validity and can be added later via update. 
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2.3.6.5. ALLOW CHANGE Option 


The ALLOW CHANGE option permits changes to be made to the current item from the 
terminal. If this option is not specified, IMS 90 refuses to carry out any requested 
changes to records on disk. 


Format: 


ALLOW CHANGE 


Programming Notes: 


1. If ALLOW CHANGE is not specified and the action program calls upon the PUT 
function and delivers to IMS 90 a record in which the value of this item has been 
changed, IMS 90 returns control to the action program with an invalid request 
indicator (O03) in the program status code. 


2. This option has meaning only in item definitions that begin with the ITEM 
statement; identifier items cannot be changed. 


3. If this item is in a supplement, the ROLE IN UPDATE for that supplement should 
be CONTROLLED. 


Example: 
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ITEM MARITAL-STATUS ALLOW CHANGE 


This example specifies that the item MARITAL-STATUS can be changed in the defined 
record to which it belongs. 


2.3.6.6. VALUE Statement 


The VALUE statement specifies the valid ranges of values an item may have when it is 
being added or changed. IMS 90 checks the validity of the item when any type of update 
(ADD, CHANGE, PUT, or INSERT) is requested and carries out the requested function only 
if the value of the item lies within the specified ranges. If the VALUE statement is omitted, 
any value consistent with the PICTURE and USAGE specified in the data division for the 
source of this item is acceptable. 





Format: 
TT Is iterat 1) (HRONGH Ii teral-2) 
VALUES ARE 





“literal-3 eT 
THRU 
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literal-1, literal-2,... 
Specify the allowable values or ranges of values for an item being added or 


changed. The values of /itera/-7, /iteral-2, ... must be in ascending order. Their 


lengths must be exactly equal to each other and to the item named by data- 
name-7 or data-name-2 in the ITEM statement. Alphanumeric literals must be 


enclosed in single quotes; numeric literals are not. 


If the item being defined is an identifier item, IMS 90 employs the ranges specified in the 
VALUE statement to recognize the defined record type. When an identifier is supplied to 
IMS 90 by an action program or by a terminal operator using UNIQUE, these range tests 
are applied to the string of items comprising the identifier. When IMS 90 is asked to 
produce the next defined record in a sequence, it applies the range tests to the items 
comprising the record key in the records read from disk. The effect of applying the VALUE 


clause to 


an identifier item in this manner is to disable access to records with keys outside 


the range specified. This could be an effective tool for file segmentation; i.e., processing A 
through E, F through L, M through R, and S through Z segments of a payroll file in stages. 


Programming Notes: 


1, 


Example: 


8 


The VALUE statement must be used for fraternal record types having the same 
source (i.e., their primary parts come from successive occurrences of the same 
indexed record) and their value ranges must not overlap. 


When the VALUE statement is used for fraternal record types from different 
sources and the value ranges of their identifiers overlap, the PREFIX statement 
must also be included. 


The VALUE statement must be used if occurrences of an indexed record 
contributing to this defined record must be distinguished from successive 
occurrences of the same indexed records that do not contribute to the defined 
file. 


12 


ITEM HOURLY-RATE ALLOW CHANGE VALUE IS 9225 THRU 15966 


In this example, the item HOURLY-RATE can be changed, but new values must fall 
between 225 and 1500 or the update is rejected. 


t 


f 
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2.3.7. Supplement Definition 


IMS 90 determines the existence of a defined record by obtaining the source of its primary 
part. A defined record can contain additional items from other logical records or repeating 
groups. Items coming from a logical record or repeating group other than the source of the 
primary part must be defined in a supplement definition. Figure 2-19 shows the format of 
the supplement definition. Statements in the supplement definition must follow the same 
sequence shown in Figure 2-19. The item definition shown in the format is required and 
is the same as the item definition for a defined record (2.3.6 through 2.3.6.6). The item 
definition for a supplement, however, cannot start with an IDENTIFIER Statement; it must 
begin with an ITEM statement. 


SUPPLEMENT supplement-name-1 


FROM stored-record-name-1 
FROM REPEATING GROUP data-name-1} 


[POINTER 1S item-name-1[,item-name-2]...] 
[FILL KEY To literal-1] 


CONTROLLED 
NEUTRAL 


item-definition [item-definition]... 


hone { controcteg: |*°"' IN _] 





Figure 2—19. Supplement Definition Format 


2.3.7.1. SUPPLEMENT Statement 

The SUPPLEMENT statement indicates the beginning of a supplement definition and 
Supplies a name for future reference within the data definition. This statement must begin 
in margin A (column 8) and be the first statement in the supplement definition. 


Format: 


SUPPLEMENT supplement-name-1 


where: 


Suppiement-name- 1 
Identifies the supplement, is 1 to 30 characters in length, and must be unique 
within the data definition. 


Example: 


8 12 





SUPPLEMENT DEPENDENT 


This example identifies a supplement named DEPENDENT. 
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2.3.7.2. FROM Statement 

The FROM statement designates the record description in the data division that describes 
the source of this supplement. The FROM statement must mediate: follow the 
SUPPLEMENT statement. 


Format: 


FROM stored-record-name- 1 


where: 


stored-record-name-l 
Refers to a O1 level group item in the data division file section. 


Programming Note: 
Any item within stored-record-name-1 may be included in this supplement if: 
= it meets constraints of length and usage (see 2.3.6.2); and 


= §its position within stored-record-name-7 comes before any item defined with the 
OCCURS clause. 


Example: 


8 12 





SUPPLEMENT DEPENDENT FROM DEPENDENT-RECORD 


The contents of the supplement DEPENDENT are supplied by the logical record 
DEPENDENT-RECORD, which is a O01 entry in the data division file section. 


2.3.7.3. FROM REPEATING GROUP Statement 
The FROM REPEATING GROUP statement designates the item, described in the data 


division with an OCCURS clause, that is to be the source of this supplement. If used, it 
must immediately follow the SUPPLEMENT statement. 


Format: 


FROM REPEATING GROUP data-name-l 


where: 


data-name-l 
Refers to a data name defined in the data division with both an OCCURS clause 
and a KEY clause. 





a 
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Programming Notes: © 
4. If data-name-7 is contained within one or two larger group items in the data 


division that are also described with the OCCURS clause, IMS 90 requires those 
descriptions to include the KEY clause. 


2. The logical record that contains data-name-7 must not be created by a UNIQUE 
ADD command or a defined file INSERT function; otherwise, the value of data- 
name-? is binary zeros and therefore, cannot contain a unique key. 


3. Any item within data-name-7 may be included in this supplement if: 
= it meets constraints on length and usage (see 2.3.6.2); and 


# its position within data-name-7 comes before any item (other than data- 
name-7 itself) defined with an OCCURS clause. 


Example: 


8 (12 

SUPPLEMENT DEPENDENT FROM REPEATING GROUP DEPENDENTS 

In this example, the contents of the supplement DEPENDENT are supplied by the 
repeating-group item, DEPENDENTS, which is a 02 level entry in the file section of @ 


the data division. DEPENDENTS is described in the data division with both an 
OCCURS clause and a KEY clause as follows: 


8 12 
02 DEPENDENTS OCCURS 5 TIMES ASCENDING KEY 1S DEP-NAME 
03 DEP-NAME PIC X(15) 
2.3.7.4. POINTER Statement 
The POINTER statement designates the items whose values are employed to locate a 
particular occurrence of this supplement’s source record. This statement is required when 
the source of this supplement is a repeating group item or a record in a nonindexed file. 


Format: 


POINTER IS item-name-1f{,item-name-2] 


where: 


item-name-1,item-name-2 
Refer to items previously defined in the current defined record definition or in a 
direct ancestor of the current defined record. Se 
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The values of item-name-1, item-name-2 ... are concatenated from left to right to form a 
character string called the POINTER. Then, if the source of this supplement is a repeating 
group item, as many right-hand characters as necessary are used to match against key 
items. The remaining left-hand characters are used to create a record key. These ‘ 
characters are justified to the left when constructing a reference key for accessing an 
indexed record. They are right-justified to create a relative record number in a nonindexed 

file. Relative record numbers are filled to the left with binary O’s. An indexed record key is 
filled to the right with spaces (hexadecimal 40). Finally, the rightmost characters of an 
indexed record key are made equal to literal-1 as specified in the FILL KEY statement, if 
any. 


lf the source of this supplement is a record in an indexed file and that record is one of a 
sequence of records that contribute items to the same defined record, the POINTER 4 
statement is employed only if the source of this supplement is the first record of that 
sequence. The values of the record keys of those records must differ only in their least 
Significant (rightmost) character positions, as specified by literal-1 of the FILL KEY 
statement. The values of the most significant characters of the record are the same for all 
records in the sequence and are determined according to the definition of the first source 

in the sequence. If that is the source of a supplement rather than the primary part of this 
defined record, a POINTER statement must be included in that supplement definition. 


Examples: 


8 12 
_ L POINTER IS REC-KEY 
2. POINTER |S EMP-NO,DEP-NAME 


In the first example, assume the primary part is EMPLOYEE and the supplement is 
DEPENDENT. Thus, REC-KEY contains a relative record number pointing to the logical 
record in a DAM file that contains the DEPENDENT data for the particular EMPLOYEE 
identifier in the primary part. 





In the second example, assume the same situation except that the DEPENDENT data 
comes from a repeating group item whose key is equal to DEP-NAME and which is 
contained in a record with a key equal to EMP-NO. 


2.3.7.5. FILL KEY Statement 


The FILL KEY statement specifies the rightmost characters of a record key. It is required if 
there is no POINTER statement or if the POINTER statement does not specify all the 
characters of a record key, and the remaining right-hand characters must have a value 
other than spaces (hexadecimal 40). 7 


Format: 


FILL KEY TO literal-1 








UP-8614 Rev. 1 SPERRY UNIVAC 0S/3 2-42 


IMS 90 APPLICATIONS Update A 


where: 


literal-l 
Specifies the rightmost character or characters of a record key and must be 


enclosed in single quotes. 


If there is no POINTER statement, the value of literal-1 must be greater than spaces 
(greater than hexadecimal 40) and also greater than the value of literal-1 in the FILL KEY 
statement, if any, in the immediately preceding supplement definition. This ts because 
each indexed record must have a record key whose value is greater than that of the record 
key of the immediately preceding record in the file. 


The length of literal-1 following the FILL KEY clause must not be longer than the part of 
the key not specified by IDENTIFIER or POINTER statements. 


Example: 


8 12 


FILL KEY TO ‘P’ 


This example applies to two applications. In the first, assume that payroll and 
dependent records are included in an indexed file. The EMPLOYEE record keys are 
emp-no,A, the DEPENDENT record keys are emp-no,D, and the PAYROLL records are 
emp-no,P. By specifying FILL KEY TO ‘P’, no POINTER statement is necessary to 
generate a pointer to the source of the supplement, PAYROLL, assuming the 
EMPLOYEE record was already named as a source for this defined record. 


Second, assume that the source of the supplement is a separate indexed file 
containing two types of records: PAYROLL and DEPENDENT. The same principle 
applies as in the first situation except that the POINTER statement is required, but 


only for the first supplement. 


2.3.7.6. ROLE IN UPDATE Statement 


The ROLE IN UPDATE statement specifies how the source of this supplement affects or is 


affected by the addition or deletion of an occurrence of this defined record. 


Format: 


CONTROLLED 


~ feowreat te | IN UPDATE 
NEUTRAL 


where: 


CONTROLLING 


Specifies that addition of an occurrence of the defined record is not to take place 
unless the corresponding occurrence of the source of this supplement already 
exists. In this way, the values of the items that point to this supplement can be 


validated. Deletion of the defined record is not affected. 
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CONTROLLED 
Specifies that the occurrence of the source of this supplement is to be added or 
deleted whenever an occurrence of the defined record is added or deleted. The 
source of this supplement must not be a repeating group item. If the source of 
_ this supplement already exists when addition is requested, a new occurrence of 
that source will replace. the old. 


NEUTRAL 
Indicates that the source of this supplement neither affects nor is affected by the 
addition or deletion of an occurrence of the defined record. This option is 
selected by default when the ROLE IN UPDATE statement is absent. 


Examples: 


8 12 





ASSUMES CONTROLLING ROLE IN UPDATE 
ASSUMES CONTROLLED 
ASSUMES NEUTRAL 


In the first example, assume that a primary part is an inventory record and the 
supplement being defined is the vendor information pertaining to this inventory 
record. The CONTROLLING option is used because normally you do not want to allow 
adding of an inventory record if no vendor information is available. 


In the second example, assume that a primary part is an employee record and the 
supplement being defined is the payroll information pertaining to that employee. The 
CONTROLLED option is specified because the adding or deleting of the employee 
information always requires the corresponding adding or deleting of the payroll 
information. | 


In the third example, assume that a primary part is a requisition record and the 
supplement being defined is from an inventory master record. The NEUTRAL option is 
specified because normally you do no want the deletion or addition of a requisition 
record that is of a temporary nature to affect the status of the inventory master record 
that is of a permanent nature. The same effect also is obtained by omitting the ROLE 
IN UPDATE statement. 
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2.3.8. Subrecord Definition 


Two or more variants of the same defined record can exist in the same data definition. 
They can differ in number of items included, positioning of the items, spelling of item 
names (used as column headers by UNIQUE), and authorization to update. A subrecord 
definition is required for each variant. The format of the subrecord definition is shown in 
Figure 2-20. 


SUBRECORD subrecord-name-1| OF subrecord-name-2 | 


ALLOW(ADD OF RECORD 
DELETE 
: ADD AND DELETE 


[subitem-definition].... 





Figure 2—20. Subrecord Definition Format 


All identifier items of the defined record are automatically included in each of its 
subrecords. The IDENTIFIER statement is used in a subrecord definition only when a new 
item name is desired. Any other item is included in the subrecord only if a subitem 
definition is present. 


2.3.8.1. SUBRECORD Statement 

The SUBRECORD statement indicates the beginning of a subrecord definition and supplies 
a name for future reference within the data definition. It must begin in margin A (column 
8). 

Format: 


SUBRECORD subrecord-name-1 


where: 


subrecord-name- 1 
Identifies the subrecord, is 1 to 30 characters in length, and must be unique 
within the data definition. 


Example: 


8 12 


SUBRECORD EMPLOYEE -SUB1 
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In this example, a variant of the defined record EMPLOYEE is defined as a subrecord 
called EMPLOYEE-SUB1. A possible reason is that information on dependents is 
contained in a nonindexed file, which cannot be the source of a defined record's 
primary part, and the dependent information must be presented interspersed with 
information from the defined record's primary part. This cannot be done in a defined 
record. Thus, a variant of the defined record must be named in the SUBRECORD 
statement. | 


2.3.8.2. OF Statement 
The OF statement is used only when other subrecord definitions have already appeared for 
a defined record. It simplifies the writing of subitem definitions when item names of 
subrecord-name-1 and subrecord-name-2 are mostly the same. 
Format: 

OF subrecord-name-2 
where: 


subrecord-name-2 | 
Refers to a previously defined subrecord within this defined record definition. 


Example: 
8 12 


SUBRECORD EMPLOYEE-SUB2 OF EMPLOYEE-SUB1 


In this example, the subrecord EMPLOYEE-SUB2 is defined. The OF statement 
indicates that the items that will make up EMPLOYEE-SUB2 are identified in the 
definition of subrecord EMPLOYEE-SUB1. | 


2.3.8.3. ALLOW ADD AND DELETE Statement 
The ALLOW ADD AND DELETE statement permits the addition and deletion of occurrences 
of this subrecord. If this statement is not included, addition or deletion of the defined 


record is not possible when it is accessed through a subfile containing this record. 


Format: 





DELETE 
ADD AND DELETE 





_ DD a 7 RECORD 
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NOTE: 


The absence of these statements in a subrecord definition disables the corresponding 
functional capability. For example, if ALLOW ADD or ALLOW ADD AND DELETE !ts not 
specified in the DEPENDENT-SUB7 subrecord definition, any input of the UNIQUE ADD or 
DELETE commands or any issuance of the CALL INSERT or DELETE functions involving the 
EMPLOYEE-SUB71 subrecord is rejected as invalid. 


Example: 


8 12 


ALLOW ADD AND DELETE 


This example allows occurrences of the subrecord identified by the SUBRECORD 
Statement to be added to or deleted from the defined file. 


2.3.9. Subitem Definition 


The components of the subrecord correspond to items previously defined in item 
definitions in the defined record definition. Except for identifier items, which are included 
automatically, a subitem definition is required for each item in the subrecord. Figure 2-21 
shows the format of the subitem definition. 


ITEM[item-alias-1 FROM] {item-name-1 
item-alias-2 


[Must app ] 
[ALLow CHANGE | 


VALUE IS penieneiiea THROUGH) literal-2 
VALUES ARE THRU 


[ptiterat-3 [ {TyBoUGH|Titerat-a))...] 





Figure 2—21. Subitem Definition Format 


2.3.9.1. ITEM Statement 


The ITEM statement includes into the subrecord a previously identified specific item from a 
preceding defined record or subrecord and optionally supplies a new name (alias) by which 
the item is known within this subrecord. The ITEM statement must be the first statement 
in the subitem definition. | 


Format: 


ITEM item-alias-1l PROM jitem-name-l 
item-alias-2 
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where: 


item-alias-1l 
Provides a name for the subitem, is 1 to 30 characters in length, and must be 
unique within the subrecord definition. If specified, this name appears as a 
column header to the terminal operator accessing this subrecord through 
UNIQUE. 


item-name- 1 
Refers to an item previously defined within this defined record definition. If this 
subrecord definition does not include an OF statement, the /tem-name-?7 option 
IS required. 


item-alias-2 
Refers to a subitem named in a previous subrecord definition; that subrecord 
must be defined as subrecord-name-2 in the OF statement for the current 
_ subrecord. This option is required if the OF statement is included. 


Programming Note: 


lf ttem-alias-7 is identical to ttem-name-7 (or item-alias-2), ttem-alias-7 and the word 
FROM can be omitted. 


Examples: 


8 12 
1. [TEM LAST-NAME 
2. ITEM LNAME FROM LAST-NAME 


Both examples include the item LAST-NAME that was previously defined in a record 
definition or subrecord definition. Example 1 retains the same name for the item; 
example 2 assigns a unique name. | 


2.3.9.2. MUST ADD Option 


The MUST ADD option specifies that this subitem must be present and contain a valid 
value in order to add: an occurrence of the defined record if it is accessed via a subfile 
containing this subrecord. If defined as numeric, the item must be nonzero; if 
alphanumeric, it must contain other than all spaces. This option is valid only when the 
ALLOW ADD or ALLOW ADD AND DELETE statement has been applied to the subrecord 
definition. 


Format: 


MUST ADD 


See 2.3.6.4 for an example. 
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2.3.9.3. ALLOW CHANGE Option 


The ALLOW CHANGE option permits changes to be made to the current item when the 
defined record is accessed through a subfile containing this subrecord. 


Format: 


ALLOW CHANGE 


Refer to 2.3.6.5 for additional information. 


2.3.9.4. VALUE Statement 


The VALUE statement specifies the valid ranges of values an item may have when it is 
added or changed, if the defined record is accessed through a subfile containing the 
current subrecord. If the VALUE statement is omitted, any value consistent with the 
PICTURE and USAGE specified in the data division for the source of this item is 
acceptable. 


Format: 


VALUES ARE THRU 


~ Pliteral- (ef literal- VI 
THRU | 


VALUE IS plersts ‘Uae literal- ‘| 


where: 


literal-1, literal-2, 
Specify the allowable values or ranges of values for a subitem being added or 
changed. The values of /tera/-1, literal-2, ... must be in ascending order. 
Alphanumeric literals must be enclosed in single quotes; numeric literals are not. 


Programming Notes: 
1. The number of literals specified may not exceed 64. 
2. IMS 90 will not update the defined record if the resulting value of this item is 


new and is not within one of the specified ranges. Instead, the status code 003 
(invalid operation) is returned in the program information block. 
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2.3.10. Subfile Definition 


Two or more variants of the same defined file can exist in the same data definition. They 
can differ in number of defined record types and in the makeup of. each type of defined 
record. A subfile definition is required for each additional variant. It describes a subset of a 
defined file independently and provides the means of accessing subrecords. Subrecords 
are accessible only via a subfile. Figure 2-22 shows the format of a subfile definition. 


SUBFILE subfile-name-1[PASSWORD | 


SEL BS ae ia fcc 


subrecord-name-l subrecord-name-2 





Figure 2—22. Subfile Definition Format 


2.3.10.1. SUBFILE Statement 


The SUBFILE statement indicates the beginning of a subfile definition and supplies an 
identifying name for future reference in password definition records and action programs. 
This statement must begin in margin A (column 8). 


Format: 


SUBFILE subfile-name-1[ PASSWORD] 


where: 


subfile-name-1 
identifies the subfile, is one to seven characters in length, and must be unique 
among defined file and subfile names within the data definition. It also must be 
different from the name of any conventional user file assigned to IMS 90. 


PASSWORD 
Specifies that subfile-name-7 is to be used as the password in the UNIQUE 
OPEN command to gain access to this subfile. lf PASSWORD is omitted, terminal 
operators using UNIQUE can access the subfile only if a password is defined by 
means of the NAMEREC file utility. 


Progra mming Note: 


Subfile names are used in the same way as defined file names within the data 
definition and where reference is made to them outside the data definition. Refer to 
the programming note in 2.3.4.1. 


——— __ re emmmmnrrierce cas aac erZZ_:;zrri TT 
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Example: 


8 12 A 

1. | SUBFILE EMP-FILE PASSWORD 

2. | SUBFILE PAY-FILE 
Assume a defined file has two record types, EMPLOYEE and PAYROLL. To restrict 
access to the PAYROLL file, two subfiles, EMP-FILE and PAY-FILE, are defined. The 
EMP-FILE can be accessed by all terminal operators, using the name of the subfile as 
the password. The PAY-FILE can be accessed only by those terminals named in a 
password definition submitted to the NAMEREC file utility. 

2.3.10.2. CONTAINS Statement 


The CONTAINS statement identifies the defined records and subrecords included in this 
subfile. 


Format: 


CONTAINS Jae Timed. record: name 1 tT a ee eer as | 
subrecord-name-1 subrecord-name-2 | 


where: 


defined-record-name-1,defined-record-name-2,... 
Identify defined records included in this subfile. 


subrecord-name-1l1,subrecord-name-2,... 
Identify subrecords included in this subfile. 


Programming Notes: 


1. No more than one entry can be included for each defined record; it can be either 
the defined record name or a subrecord name. 


2. Entries must be in the same order as their corresponding defined record 
definitions appeared previously in the data definition. 


3. Before an entry is submitted for a defined record, an entry must be submitted for 
every direct ancestor of that defined record. 


Example: 


8 12 


CONTAINS EMPLOYEE-SUB 


In this example, the subfile EMP-FILE consists of just one type of defined record, 
under its subrecord name EMPLOYEE-SUB. 








UP-8614 Rev. 1 SPERRY UNIVAC OS/3 2-51 
IMS 90 APPLICATIONS 


2.4. DATA DEFINITION EXAMPLES 


2.4.1. Example of Simple Defined File 


Data definition language used with a simple defined file named STATES is shown in 
Figures 2-23 and 2-24. The STATES file is derived from ST-FILE, whose first few records 
are shown in Figure 2-23. A 14-byte field at the beginning of each record contains its key. 
The record is named STATE-REC and the key is named STATE-NAME. _ 


The data definition coding is shown in Figure 2-24a. The first few records of STATES are 
shown in Figure 2-24b as IMS 90 delivers them to action programs, and in Figure 2-24c 
as UNIQUE lists them at terminals. Each record contains an identifier item named STATE, 
and two other items named STATE-POP and CAPITAL. These names appear at terminals 
as column headers. 


The defined record is named STATE-RECORD. The programmer accessing the defined file, 
STATES, must provide a place for the defined record to be received in his action program. 
Figure 2-24d shows how a record area for STATE-RECORD is described on a coding form 
in a COBOL action program. Figure 2-24e shows the same for BAL. 


ALABAMAAAAAAAAS 344416 5MONTGOMERYAAAA2 2 
ALAS KAAAAAAAAAB 83821735 UN EAUAAAAAAAA 4 9 
AR 1 ZONAAAAAAAAB 177248 4PHOEN | XAAAAAAAS 8 
ARKANSASAAAAAAB1932295LITTLE ROCKAAA25 
CALIFORN!AAAAA19953134SACRAMENTOAAAA3 1 
COLORADOAAAAAAB 2 267259D ENV ERAAAAAAAA 3 8 
CONNECTICUTAAAS 383221 7HART FORDAAAAAAD 5 


DE LAWAR EAAAAAAB 85.48 1B 4D0V ERAAAAAAAAAB 1 
FLOR | DAAAAAAAAB 678944 3TALLAHASSEEAAA27 
GEORG | AAAAAAAAB 4589573 AT LAN TAAAAAAAAD 4 





Figure 2—23. Excerpt from a Sample Indexed State File (ST-FILE} 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. BASIC-DATA-DEF. 


DATA DIVISION. 
FILE SECTION. 
FD ST-FILE. 
O01 STATE-REC. 


02 STATE-NAME P 
02 STATE-POP P 
O2 CAPITAL P 
02 ENTRY P 
DEFINITION DIVISION. 
DEFINED FILE STATES PASSWORD 


DEFINED RECORD STATE-RECORD 
FROM STATE-REC 


IDENTIFIER STATE FROM STATE-NAME 
ITEM STATE-POP 
ITEM CAPITAL. 




















a. Definition of STATES in data definition language 










ALABAMAAAAAAAAS 344416 5M0NTGOMERYAAAA 
ALAS KAAAAAAAAAG 6362173 IUNEAUAAAAAAAA 
ARI ZONAAAAAAAAS 177248 4PHOEN I XAAAAAAA 
ARKANSASAAAAAAG1932295LITTLE ROCKAAA 
CALI FORNIAAAAAI9953134SACRAMENTOAAAA 
COLORADOAAAAAAS 22872590 ENV ERAAAAAAAA 
CONNECT ICUTAAAG 363221 7HART FORDAAAAAA 
DE LAWAR EAAAAAAB 8548 184D0V ERAAAAAAAAA 
FLOR | DAAAAAAAAB 678 9443TALLAHASSEEAAA 
GEORG | AAAAAAAAS 45 89573ATLANTAAAAAAAA 













b. First block of STATES as delivered to an action program 


Figure 2—24. Defined File STATES (Part 1 of 2) 


2-52 


_ 
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“ STATE STATE-POP CAPITAL 















ALABAMA 3,444,165 MONTGOMERY 
ALASKA 362,173 JUNEAU 
ARIZONA — 1,772,484 PHOENIX 
ARKANSAS 1,932,295 LITTLE ROCK 
CALIFORNIA 19,953,134 SACRAMENTO 
COLORADO 2,207,259 DENVER 
CONNECTICUT 3,932,217 HARTFORD 
DELAWARE 548,104 DOVER 

. FLORIDA —6m6 789, 443 TALLAHASSEE 

. GEORGIA 4,589,573 ATLANTA 








c. First block of STATES as listed at a terminal display by UNIQUE 


12 


WORK-AREA | 
82 STATE-RECORD. 
93 STATE PIC X(14). 


B83 STATE-POP PIC 9(8). 
O93 CAPITAL PIC X(14). 

S-STATE-RECORD. 

83 S-STATE PIC X. 

83 S-STATE-POP PIC X. 

83 S-CAPITAL PIC X. 





d. Description of STATE-RECORD in COBOL action program 


12 


WORK DSECT WORK AREA 
RECORD EQU ° 
SNAME DS XL14 STATE NAME 


SPOP DS XL8 STATE POPULATION 
SCAPITAL DS XL14 STATE CAPITAL 


SNAME#S DS X STATE NAME STATUS BYTE 
SPOP#S DS xX STATE POPULATION STATUS BYTE 
SCAP#S DS X STATE CAPITAL STATUS BYTE 





e. Description of STATE-RECORD (labeled RECORD) in BAL action program 


Figure 2—24. Defined File STATES (Part 2 of 2) 
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2.4.2. Example of Subfile 


An example of the use of a subfile definition to restrict access to a defined file is shown in 
Figure 2-25. Compare this example to the example shown in Figure 2-24. Both data 
definitions deal with the same source data (the ISAM logical file ST-FILE in Figure 2-23). 
Both data definitions make the defined file STATES available to action programs and, via 
UNIQUE, to the terminal operator. 


Where a subrecord is defined, it can be accessed only via the subfile, which must be 
described in the SUBFILE and CONTAINS statements (Figure 2-25a). Figures 2-24b 
through 2-24e still apply to the new data definition as well as the old, where data was 
accessed via the defined file name STATES. The new data definition, however, also makes 
the subfile, SUBFIL, available to action programs (including UNIQUE). Thus, b and c in 
Figure 2-25 illustrate the data that can be accessed via the subfile name, SUBFIL. In this 
case, only two items are delivered to the action program. Their item names, as employed 
by UNIQUE, are changed from STATE and STATE-POP to NAME-OF-STATE and - 
POPULATION, respectively. Figures 2-25d and 2-25e show how the programmer provides 
a place for subrecords to be received in a COBOL or BAL action program. 


8 12 


IDENTIFICATION DIVISION. 
PROGRAM-ID. SUB-DEF. 
DATA DIVI 
FILE SECTION: 
FD ST-FILE. 


01 STATE-REC. 
02 STATE-NAME 
02 STATE-POP 
02 CAPITAL 
02 ENTRY 


DEFINITION DIVISION. 
DEFINED FILE STATES PASSWORD 


DEFINED RECORD STATE-RECORD 
FROM STATE-REC 
IDENTIFIER STATE FROM STATE-NAME 
ITEM STATE-POP 
ITEM CAPITAL 


SUBRECORD SUB-STATES 
IDENTIFIER NAME-OF-STATE FROM STATE 
ITEM POPULATION FROM STATE-POP 
SUBFILE SUBFIL PASSWORD 
CONTAINS SUB-STATES. 


a. Definition of STATES and SUBFIL 





Figure 2-25. Subfile Definition Restricting Access to a Defined File (Part 1 of 2) 
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b. First block of SUBFIL as delivered to an action program 


NAME-OF-STATE 


ALABAMA 
ALASKA 
ARIZONA 


. ARKANSAS 


CALIFORNIA 
COLORADO 
CONNECTICUT 
DELAWARE 


. FLORIDA 


GEORGIA 


c. First block of SUBFIL as listed at a terminal by UNIQUE 


d. Description of SUB-STATES in COBOL action program 


1 


WORK 
SUBREC 


SNAME 
SPOP 
SNAME#S 
SPOP#S 


e. Description of SUB-STATES (labeled SUB-REC) in BAL action program 


Figure 2—25. Subfile Definition Restricting Access to a Defined File (Part 2 of 2} 
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ALABAMAAAAAAAAB 3444165 
ALAS KAAAAAAAAAB 8382173 
ARI ZONAAAAAAAAB 1772484 
ARKANSASAAAAAAG 1932295 
CALI FORNIAAAAA1 9953134 
COLORADOAAAAAAB 2287259 


CONNECT ICUTAAA8 3932217 
DE LAWAR EAAAAAAB 8548194 
FLOR | DAAAAAAAASB 6789443 
GEORG | AAAAAAAAB 4589573 


POPULATION 
3,444,165 


392,173 


1,772,484 
1,932,295 
19,953,134 
2,287,259 
3,832,217 


948,194 


6,789,443 
4,589,573 


10. 


DSECT 
EQU 
DS 

DS 

DS 

DS 


12 


WORK-AREA. 
92 SUB-STATES. 
93 NAME-OF-STATE PIC X(14). 


93 POPULATION PIC 9(8)..: 


92 S-SUB-STATES. 


93 S-NAME-OF-STATE PIC X. 
63 S-POPULATION PIC X. 





WORK AREA 


STATE NAME 
STATE POPULATION 


STATE 
STATE 


NAME STATUS BYTE 
POPULATION STATUS BYTE 





2-55 


UP-8614 Rev. 1 SPERRY UNIVAC OS/3 2-56 


IMS 90 APPLICATIONS 


2.4.3. Example of Supplements in Defined File 


The data definition for CITIES in Figure 2-27a: illustrates the use of supplements in a 
defined file. Each defined record in CITIES comes from three different logical records on 
disk. Two of these come from the indexed file CI-FILE, an excerpt of which is shown in 
Figure 2-26. Another comes from ST-FILE, shown in Figure 2-23. 


The records of the indexed file CI-FILE occur in pairs. There are two records for 
ABERDEEN, two for ABILENE, etc. The first supplies the primary part of CITY-RECORD; the 
second supplies a supplement. Both have record keys in the same character positions: 1 
through 22. The values of these keys differ only in character position 22. The first record 
contains the space character and the second record contains the number 1. These values 
cause the logical records to be in ascending order and identify the type of logical record 
(CITY-REC or CITY-REC-TRAILER), a necessary function in case one of the pair is missing. 
IMS 90 operates on the single entity represented by the defined record. Therefore, it adds, 
deletes, and displays both types of records together. If the first record is missing, the 
second is ignored by IMS 90. If the second record is missing, IMS 90 supplies spaces for 
the item named STATE. 


The second file ST-FILE contains a single type of logical record, STATE-REC. that 
contributes a supplementary part of the defined record. It is accessed by means of a 
pointer. As a record in an indexed file, STATE-REC contains a record key. The pointer that 
IMS 90 constructs from NAME-STATE in the CITY-REC-TRAILER logical record is used as a 
search key to match against the record key STATE-NAME in the STATE-REC record. In this 
way, the secondary part is located. If ST-FILE is a nonindexed file, there will be no record 
key in the STATE-REC record. The pointer will be a file relative record number instead. It 
still will be constructed in the same way and used for the Same purpose as an indexed file 
key. If IMS 90 fails to find a STATE-REC record, it supplies zeros for the item named 
STATE-POP in the defined record supplement. 





ABE RDE ENAAAAAAAAAAAAAASB 6 2 6 4 6 TAAAAAAA 
ABE RDE ENAAAAAAAAAAAAA 1$ OU THADAKOTAAA 
AB I L EN EAAAAAAAAAAAAAAAS 6 8 9 6 5 SAAAAAAA 
ABIL EN EAAAAAAAAAAAAAA 1T EX A SAAAAAAAAA 
A LAME DAAAAAAAAAAAAAAAAB 6 7 8 9 6 BAAAAAAA 
A LAME DAAAAAAAAAAAAAAA ICAL I FORN | AAAAA 
ALBAN YAAAAAAAAAAAAAAAAB 1757 8 LAAAAAAA 
ALBAN ¥AAAAAAAAAAAAAAA 1 N EWAY 0 R KAAAAAA 










Figure 2—26. Indexed File with Two Logical Records for Each City (CI-FILE) 
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—EDENTIFICATION DIVISION. 


PROGRAM-ID. SEC-PART-DEF. 
DATA DIVISION. 
FILE SECTION. 


FD 
01 


FD 
01 


CI-FILE. 

CITY-REC. 

02 CITY-NAME PIC X(21). 
02 RCD-TYPE PIC X. 

02 CITY-POP PIC 9(7). 
02 FILLER PIC X(7). 
CITY-REC-TRAILER. 

02 CITY-1D PIC X(21). 
02 TYPE-RCD PIC X. 

02 NAME-STATE PIC X(14). 
ST-FILE. 

STATE-REC. 

02 STATE-NAME PIC X(14). 
02 STATE-POP PIC 9(8). 
02 CAPITAL PIC X(14). 
02 ENTRY PIC 9(2). 


DEFINITION DIVISION. 
DEFINED FILE CITIES 
DEFINED RECORD CITY-RECORD 


FROM CITY-REC 
ALLOW ADD AND DELETE 


IDENTIFIFER CITY FROM CETY-NAME 
ITEM CITY-POP 


SUPPLEMENT CITY-PART-1 


FROM CITY-REC-TRAILER 
FILL KEY TO ‘1° ASSUMES CONTROLLED ROLE IN UPDATE 
[ITEM STATE FROM NAME-STATE 


SUPPLEMENT CITY-PART-2 


FROM STATE-REC 
POINTER IS STATE 


ITEM STATE-POP. 


a. Data definition of CITIES showing supplements 


Figure 2—27. Defined File CITIES (Part 1 of 2) 
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. ABERDE ENAAAAAAAAAAAAAS 6 26467S0UTHADAKOTAAAS #666257 
ABIL EN EAAAAAAAAAAAAAAS 6 8 9653 T EX ASAAAAAAAAAL1L 196739 


- ALAME DAAAAAAAAAAAAAAAB B 7696 8CALIFORNTAAAAAI9953134 
AL BAN YAAAAAAAAAAAAAAAB 17578 TN EWAY 0 RKAAAAAAS 4589575 





b. CITIES as delivered to an action program 


" CITY CiTY-POP STATE STATE-POP 


ABERDEEN 26,467 SOUTH DAKOTA 666,257 
ABILENE 89,653 TEXAS 11,196.736 
ALAMEDA 70,968 CALIFORNIA 19,953,134 
ALBANY 175,781 NEW YORK 4,589,575 





c. CITIES as listed at a terminal by UNIQUE 


12 


WORK-AREA. 
02 CITY-RECORD. 
03 CITY Pic X 
93 CITY-POP PIC 9 
93 STATE PIC X 
03 STATE-POP PIC 9 
S-CITY-RECORD. 
03 $-CITY PIC 
83 S-CITY-POP PIC 
83 S-STATE PIC 
83 S-STATE-POP PIC 





d. Description of CITY-RECORD in COBOL action program 


1 10 16 


WORK | DSECT WORK AREA 
CTYREC EQU 

SCTYNM DS 

SCTYPOP ODS 


SSTATE DS 
SSTPOP DS 
SCTYNM#S DS 
SCPOP#S DS 
SSTATE#S DS 
SSTPOP#S DS 





e. Description of CITY-RECORD (labeled CTY-REC) in BAL action program 


Figure 2—27. Defined File CITIES (Part 2 of 2) 
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2.4.4. Examples of Hierarchical Records in Defined Files 


Figures 2-28 through 2-32 show portions of defined files and the data definitions needed 
to define: a 7 : | 


= a logical indexed file containing two record types; © 
s a logical indexed file. containing a repeating group item; and 
= two logical indexed files. 


Note that three alternative data definitions describe the same defined file taken from these 
various sources. The sources themselves differ in content and organization. Nevertheless, 
in these examples there is no difference in the resulting defined file that is delivered to 
the action program regardless of the defined file’s source, nor is there any difference in 
the way the defined file appears at the terminal when accessed via UNIQUE. Actually, the 
logical files can be reorganized and the defined file redefined without any change to action 
programs or terminal operating procedures. oe oe 


2.4.4.1. Hierarchical Defined Records Using Several Record Types as Source 


Figure 2-28 illustrates the first few logical records in the indexed file, ST-CITY, from which 
the defined records of the BIGCITY defined file are taken. Figure 2-29 provides the data 
definition for the defined file BIGCITY, which contains records arranged in a hierarchical 
structure within set occurrences. 


The order of records in the BIGCITY defined file is: identical to the order of their primary 
parts in the logical file ST-CITY. In fact, the order of records in a defined file is derived 
from the corresponding record sequence in the logical file. In this case, the source of each 
parent record is followed directly by the logical source of its child records. This is just one 
of several ways the sources of parent- and child-type defined records can be related in 
logical files. | 


The resulting records defined in this data definition are delivered to the user action 
program and appear at the terminal via UNIQUE, as shown in Figures 2-33, 2-34, and 
2-35. 


2.4.4.2. Hierarchical Defined Records Using Repeating Group Item as Source 


The logical indexed file, ST-RG, shown in Figure 2-30, contains the same information as 
the ST-CITY logical file (Figure 2-28), but is organized differently. Here the city information 
is contained in a table within each state record. The data definition in Figure 2-31 shows 
how the BIGCITY defined file would be described if its source were the logical file ST-RG. 
The resulting records defined in this data definition are delivered to the user action 
program and appear at the terminal via UNIQUE as shown in Figures 2-33, 2-34, and 
2-35. 
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ALABAMAAAAAAAAMONT GOMER YAAAA 

A LABAMAAAAAAAAB I RMI NG HAMAAAAAAAAAAAAAAAS 3 2 5 8 8 BAAAAAAA 
A LABAMAAAAAAAAH UNT SV IL EAAAAAAAAAAAAAAAAS 1 438 8 BAAAAAAA 
ALABAMAAAAAAAAM OB | L EAAAAAAAAAAAAAAAAAAA SB 2 15 8B BAAAAAAA 
AL ABAMAAAAAAAAM ONT GOMER YAAAAAAAAAAAAAAA B 15 2 6 6 BAADAAAA 
ALAS K AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA J UNE AUAAAAAAAA 
ALAS KAAAAAAAAAA NC HO RAG EAAAAAAAAAAAAAAAA 8 85 2 6B BAAAAAAA 


ALAS KAAAAAAAAAF A1 RBANK SAAAAAAAAAAAAAAAAS 8 8 19 8 BAAAAAAA 
ALAS KAAAAAAAAA J UN EAUAAAAAAAAAAAAAAAAAAA B 68 6 8 8B BAAAAAAA 
AR 1 ZONAAAAAAAAADADAAAAAAAAAAADAAAAAAAAAAA PHO EN 1 XAAAAAAA 
AR 1 ZONAAAAAAAAP HO EN f XAAAAAAAAAAAAAAAAAAS 5 15 8 6 BAAAAAAA 
AR t ZONAAAAAAAAT UC S$ ONAAAAAAAAAAAAAAAAAAA 8 2 4 68 6 BAAAAAAA 
ARK ANS ASAAAAAAAAAAAAAAAAAAAAAALAAAAAAAAL ETT LEAR OC KAAA 





Figure 2—28. ST-CITY Indexed File with Two Record Types 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. BIG-CITY-DEF. 
DATA DIVISION. 

FILE SECTION. 

FD ST-CITY. 


~—6©01:) 0 «OSTATE-REC. 
02 STATE X( 14). 
O02 FILLER X(25). 
02 CAPITAL X( 14). 


CITY-REC. 

02 STATE X(14). 
O02 CITY | X(25). 
02 POPULATION 9(7). 

02 FILLER X(7). 


DEFINITION DIVISION. 
DEFINED FILE BIGCITY 
DEFINED RECORD STATE-RECORD 
FROM STATE-REC 
IDENTIFIER STATE 
ITEM CAPITAL 
DEFINED RECORD CITY-RECORD 
FROM CITY-REC 
PARENT 1S STATE-RECORD 
IDENTIFIER CITY 
ITEM POPULATION. 





Figure 2—29. Data Definition for the Defined File BIGCITY 
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& A LABAMAAAAAAAAM ONT GOMER YAAAAB 8 8 4 
BI RMI NGHAMAAAAAAAAAAAAAAAB 3 258 88 
MOB I L EAAAAAAAAAAAAAAAAAAAB 215 8 89 
HUNTSVEL EL EAAAAAAAAAAAAAAAS 1 43668 
MONT GOMER YAAAAAAAAAAAAAAAB 15 2808 — 


ALA SK AAAAAAAAA J UN EAUAAAAAAAAS 6 83 
ANCHO RAG EAAAAAAAAAAAAAAAA B 8 5 2868 


FAIRBANK SAAAAAAAAAAAAAAAAB 819880 
JUN EAUAAAAAAAAAAAAAAAAAAA 8 6 8 6 8 8B 


AR I ZONAAAAAAAAP HO EN I XAAAAAAAS 6 8 2 
PHOEN I XAAAAAAAAAAAAAAAAAAB 5 15868 
TUC S ONAAAAAAAAAAAAAAAAAAA 8 2 46868 


ARKANSASAAAAAAL ITT LEAROCKAAAG 86 1 
LITTLEAROC KAAAAAAAAAAAAAAB 135688 





Figure 2—30. STATE-RG Indexed File Containing a Repeating Group Item 
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IDENTIFICATION DIVISION. 
PROGRAM-ID. BIG-CITY-DEF-1. 


© DATA DIVISION. 
FILE SECTION. 
FD ST-RG. 


O01 STATE-REC. 


02 STATE PIC X(14). 
02 CAPITAL PIC X(14). 
02 COUNT PIC 9(4). 
02 CITY-ENTRY: 
OCCURS 0 TO 5 TIMES 
DEPENDING ON COUNT 
ASCENDING KEY 1S CITY. 
03 CITY PIC X(25). 
03 POPULATION PIC 9(7). 
DEFINITION DIVISION. 
DEFINED FILE BIGCITY 
DEFINED RECORD STATE-RECORD 
FROM STATE-REC 
IDENTIFIER STATE 
ITEM CAPITAL 
DEFINED RECORD CITY-RECORD 
FROM REPEATING GROUP CITY-ENTRY 
PARENT IS STATE-RECORD 


@ | IDENTIFIER CITY 
- | ITEM POPULATION. 


Figure 2—31. BIGCITY Data Definition Derived from a Repeating Group Item 











UP-8614 Rev. 1 SPERRY UNIVAC OS/3 2-62 
IMS 90 APPLICATIONS 


2.4.4.3. Hierarchical Defined Records Using Two ISAM Files as Source 


A third data definition of the BIGCITY defined file is given in Figure 2-32c. In this example, 
the city and state records come from sources that are in two different ISAM files; the state 
records come from the logical file ST-FILE, and city records come from the logical file EN- 
CITY. Each state record contributes a pointer that IMS 90 uses to locate the set of city 
records that are its child-type records in the hierarchy. Figure 2-32 shows the relationship 
of the two ISAM files to each other and to the defined file. 


Figures 2-33, 2-34, and 2-35 show the resulting records defined in this data definition as 
they are delivered to the user action program and as they appear at the terminal via 
UNIQUE. 


ALAS KAAAAAAAAAB 8382173 JUN EAUAAAAAAAAS 9 DATA DIV 
ARI ZONAAAAAAAAB 177248 4PHOEN I XAAAAAAAS8 FILE SEC 
ARKANSASAAAAAAB1932295LITTLEAROCKAAA25 ED ST-FI 
CALI FORNIAAAAA19953134SACRAMENTOAAAA3 1 

COLORADOAAAAAAB 226725 9D ENV E RAAAAAAAA3 8 01 STATE-REC. 
CONNECT ICUTAAAS 383221 7HART FORDAAAAAAG 5S | STATE-NAME 
DE LAWAR EAAAAAAGB5 48 1 84D OV ERADLAAAAAAG D) STATE-POP 
FLOR I DAAAAAAAAGE7B89443TALLAHASSEEAAA27 CAPITAL 
GEORG | AAAAAAAAG 4589573 ATLANTAAAAAAAABA 4 ENTRY 


-CITY. 


CA 

ALABAMAAAAAAAAB8 344416 5MONTGOME RYAAAA2 2 PROGRAM-1D 
IS 

TI 

L 


i 
0 
E 


I 

E-CY-REC. 

02 ENTRY-NUMBER 
02 CITY-NAME 

02 CITY-POP 

! 
} 


DEFINITION DIVISION. 
DEFINED FILE BIGCITY PASSWORD 
DEFINED RECORD STATE-RECORD 


FROM STATE-REC 
IDENTIFIER STATE FROM STATE-NAME 


ITEM CAPITAL 
[TEM ENFRY HIDDEN 


DEFINED RECORD CITY-RECORD 
FROM E-CY-REC 


a. ‘ST-FILE, alphabetic {SAM file 


@Iwi LMINGTON 6085088 


B2ER I EAAAAAAAAAAAAAAAAAAAAAB 13 4688 
B2PH! LADELPH I AAAAAAAAAAAAAA 2 615988 





Z2LPEOR | AAAAAAAAAAAAAAAAAAAA SB 135888 
22B 1 RM! NGHAMAAAAAAAAAAAAAAAG 325868 
22HUNTSVI LL EAAAAAAAAAAAAAAASB 1439088 
2 2M0B I L EAAAAAAAAAAAAAAAAAAA B 2 15688 
2 2MONT GOME RY AAAAAAAAAAAAAAAB 15 2868 
23PORT LANDAAAAAAAAAAAAAAAAA 6 8 6 78 8B 
24S TALOU I SAAAAAAAAAAAAAAAAAB 6 6 5898 Y FROM CITY-NAME 
ZSLETTLEAROC KAAAAAAAAAAAAAAB 135888 ITEM POPULATION FROM CITY-POP. 





c. Data definition for BIGCITY defined file 


b. EN-CITY, city data ordered by state entry number 





Figure 2—32. Derivation of BIGCITY Defined File from Two Distinct Files Using Pointers 
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(2.4.4.4. Defined File Resulting from Different Logical File Sources 


Figure 2-33 illustrates the first defined records of the BIGCITY defined file that IMS 90 
delivers in main storage to the user action program in response to a series of GET function 
calls. When each GET function call is issued, all fields of a defined record plus one status 
byte per field are moved to the action program. 


ALABAMAAAAAAAAM ONT GOMER YAAAA 
A LABAMAAAAAAAAB | RM ING HAMADAAAAAAAAAAAAAA 8 3 258 88 
A LABAMAAAAAAAAH UN T SV ILL EAAAAAAAAAAAAAAAB 1 43808 
A LABAMAAAAAAAAM OB I L EAAAAAAAAAAAAAAAAAAAB 2158066 
ALABAMAAAAAAAAM 0 NT GOMER Y¥AAAAAAAAAAAAAAAS 15 2888 
ALAS KAAAAAAAAA J UN E AUAAAAAAAA 


ALAS KAAAAAAAAAA NC HO RAG EAAAAAAAAAAAAAAAA 8 6 5 2: 8 98 
ALAS KAAAAAAAAAF AL RBANK SAAAAAAAAAAAAAAAAS 6198 88 
ALAS KAAAAAAAAA J UN E AUAAAAAAAAAAAAAAAAAAA 86 6 8 6 8 88 


ARF ZONAAAAAAAAP HO EN I XAAAAAAA 

AR 1 ZONAAAAAAAAP HO EN I XAAAAAAAAAAAAAAAAAAB 5 15898 
AR 1 ZONAAAAAAAAT UE S$ ONAAAAAAAAAAAAAAAAAAA 0 246999 
ARKANSASAAAAAALITTLEAROC KAAA | 





Figure 2—33. Defined Records from the BIGCITY File as Delivered to Action Programs 


Figure 2-34 is the terminal display of the BIGCITY file in response to a UNIQUE LIST 
command. Note that a leading asterisk indicates a line of item names that serve as column 
headers. A period indicates a line of item values that comprise an occurrence of a defined 
record. Because the identifier of each city record consists of both state and city names, 
UNIQUE replaces the state name with a hyphen to conserve screen space. 


Figure 2-35 and 2-36 illustrate the corresponding description of the receiving space that 
accommodates the parent and child defined records in the user COBOL and BAL action 
programs. 
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* STATE CAPITAL 

© 2C1TY POPULATION 
ALABAMA MONTGOMERY 
-BIRMINGHAM 325,808 
-HUNTSVILLE 143,609 
-MOBILE 215,968 
-MONTGOMERY 152,668 
ALASKA JUNEAU 
-ANCHORAGE 52,900 
-FAIRBANKS 19,806 
- JUNEAU 6,889 
ARIZONA PHOENIX 
-PHOENIX 515,908 
-TUCSON 249,008 
ARKANSAS LITTLE ROCK 


Figure 2—34. Defined Records from the BIGCITY File as Listed at the Terminal by UNIQUE 


12 
WORK-AREA. 
82 STATE-RECORD. 
83 STATE PIC X (14). 
83 CAPITAL PIC X (14). 
82 S-STATE-RECORD. 
83 S-STATE PIC X. 
83 S-CAPITAL PIC X. 
CITY-RECORD. 
93 STATE PIC X (14). 
93 CITY PIC X (25). 
83 POPULATION PIC X (7). 
S-CITY-RECORD. 
83 S-STATE PIC X. 
83 S-CITY PIC X. 
83 S-POPULATION PIC X. 





Figure 2—35. Description of STATE-RECORD and CITY-RECORD in COBOL Action Program 
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1 10 


WORK DSECT WORK AREA 
STREC EQU 

SSTATE DS 

SCAPIT 

SSTATE#S 

SCAPIT#S 


CITY#REC 
SCSTATE 
SCCITY 
SCPOP 
SCSTAT#S 
SCCITY#S 
SCPOP#S ODS 





Figure 2—36. Description of STATE-RECORD and CITY-RECORD in BAL Action Program 


2.5. EXECUTING DATA DEFINITION PROCESSOR 


After the data definition is prepared, it must be submitted to the data definition processor 
(data definition processor), whose module name in OS/3 is DT3DF. The data definition 


processor writes a data definition record into the named record file (NAMEREC) and 


produces a diagnostic listing. Multiple defined files must be created in separate runs of the 
data definition processor but can be written to the same NAMEREC file. The data 
definition processor cannot write to the NAMEREC file while IMS 90 is accessing 
NAMEREC. The NAMEREC file must be initialized before the data definition processor is 
executed for the first time. Initialization procedures are described in the IMS 90 system 
support functions user guide/programmer reference, UP-8364 (current version). Note that 
if the NAMEREC file is reinitialized at any time, all data definitions must be recompiled. 


2.5.1. Data Definition Processor Options 


You can present parameters to the data definition processor via the optional PARAM 
statement. The format is: 


// PARAM parameter-1 [,..., parameter-n] 


PARAM statements should be placed immediately following the EXEC job control 


Statement (// EXEC DT3DF) in the execution job control stream. The data definition 
processor prints these on the first page of the diagnostic listing. If a PARAM statement 
format error or an illegal parameter is encountered, a system console message is produced 


‘and the data definition run is terminated. Only one blank precedes the P of the word 


PARAM. 


To produce a single-spaced diagnostic and source listing, you must specify the following 


PARAM statement: 


// PARAM LST=(L,S) 
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The format for the source library PARAM job control statement is: 


// PARAM IN=program-name/file-name 


where: 


program-name 
Is a 1- to 8-character name of your source data definition program. 


file-name 
Is a 1- to 8-character name used to identify the file on which your source data 
definition program resides. This name must appear on the LFD job control 
statement you used to define this device. If the file-name is omitted, the name 
SYSSRC is automatically supplied. 


The format of the PARAM statement for copy library input is: 


// PARAM LIN=file-name 


where: 


file-name 7 
Is a 1- to 8-character name used to identify the file on which your COPY library 
resides. This name must appear on the LFD job control statement you used to 
define the device. If the file-name is omitted, the name COPYS is automatically 
Supplied. You supply the COPY element-name in your source data definition 
program via the COPY clause. | : 


There are no output options available for the data definition processor. (7/7 PARAM 
OUT=(M) is specified only for a COBOL action program, never for the data definition 
processor.) 
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© 2.5.2. Execution Run Streams 


To execute the data definition processor, having previously allocated the NAMEREC file 
using the ZP#NRU utility or the configurator, you code and execute a job such as DATADF. 
(See sample control stream in Figure 2-37.) The main storage eapiement ror the data 
definition processor is 5OK bytes. 7 


JOB DATADF, ,C9O8 

DVC 28 // LFD PRNTR 

OPTION DUMP 

DVC 50 // VOL DS9999 // LBL AMEE Ge DS9999 // LFD |SAMNRF 
WORKI 

WORK2 

WORK3 

EXEC DT3DF 


source cards 


source cards 





@ | Figure 2—37. Executing the Data Definition Processor (DT3DF)} 


In addition to the job control and PARAM statements already discussed, the most 
important part of your input to the data definition processor is your source statements 
(2.3). Figure 2-16 provides a consolidated format of the defined file definition which can 
be used when studying the sample diagnostic listing produced by the OS/3 data definition 
processor (see Figures 2-38 and 2-39). 


2.5.3. Data Definition Processor Output Listing 


The printed output provided by the data definition processor comprises a source listing of 
the input to the data definition processor and, when the processor has successfully 
created a data definition record, a COBOL description of the defined file. Each defined 
record and subrecord is described as a COBOL group item such as required in a COBOL- 
written action program accessing the file. Included with each defined record description, 
the processor listing describes the item status bytes, one for each elementary item defined 
in the data definition record above it. The processor generates each item status byte data 
name by prefixing the data name of the corresponding elementary item with ‘S’-. This 
provides a data name for accessing each item’s status byte if a test is made for the 
completeness and validity of data transfer after retrieving a record from the defined file in 
the action program. 
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Figure 2-38 is a listing compiled by the data definition processor for the defined file 
SECOUNT. Part 1 lists the source input. Part 2 shows the COBOL description of the 
defined file, the description of the defined record LIQUOR, and the description of the item 
status bytes. The last line of output contains the statement DATA DEFINITION COMPLETE, 
followed by compilation time figures. When a subfile definition is input to the data 
definition processor, the last pages of the output listing have the format shown in Figure 
2-39, in which a defined file and subfile (ZR and CH-ZR) are described. 


LINE NO, SEQ, SOURCE STATEMENT 


90901 IDENTIFICATION DIVISION, 
90302 PRIGRAMeID,  O0°TA, 

90903 JATA DIVISION, 

90904 FILE SECTION, 

50905 FD OUEIN, 

90308 31 DUE-IN, 

90907 O2 FILLE® PIC x, 

9030n 02 DUEIN@KEY, 

90308 03 DUE If NenAME PIC X15), 

90310 03 OQUEtNeSIZE PIC x¢2), 

905911 O2 VENDOR PIC 9(2) YSAGE CAnP-4, 
9091? U2 QUAN-OUE-IN PIC 942) USAGE COmPH4, 
90913 OUEOUT, 

90916 DUE-OUT, 

90915 O2 FILLES PIC X, 

50314 U2 DUEQUT-KEY, 

903917 O03 DUFDUT@NAME PIC X(1L3), 

903,A O03 DUPFUUT“SIZE PIC Xxt2), 

90919 02 DUEOUT-TOTAL PIC 903) USAGE CUMP~«, 
90920 U2 DUEDUT-ORDER UCCURS 5 TIMES, 

90921 03 CUSTOMER@KEY PIC X¢5), 

90922 03 QUANSDUESOUT PIC X(9), 

90923 PRODFIL, 

90326. PRODPEC, 

90525. G2 PRUD-KEY, 

90926 03 PRID-N&ME PIC X(15), 

90927 03 PRaNDWSIZE PIC xt2), 

90928 O2 PROD<TYPE PIC X¢2), 

90929 02 ONeHAND PIC 9¢2) USAGE CUMP~s, 
90330 O2 DUETIN-FLAG PIC X, 

90931 U2 OUE-QUT~FLAG PIC X, 

90532 O2 STUCK=LEVEL PIC 9(2) USAGE COMP-«, 
90933 v2 REURDFRePOINT PIC 92) USAGE COMP-«, 
90936 G2 UNIT=-NFsSISSUE PIC x2), 

90935 C2 COST PIC 9t4)V99 USAGE CUMped, 
30934 O2 SUBSTITUTE PIC XCLT), 

90937 U2 PROD-VENDOR PIC 942) USAGE COMP=«, 
9093R O2 FILLER PIC xXt28), 

590939 FO VENDUR, 

90349 21 VENDREC, 

9034} -02 VEND-NAME PIC X20), 

90342 02 VEND-AODOR PIC X€35), 

90248 JEFINITION OTVISION, 

90546 DEFINED FILE SECOUNT PaSSWORN, 

90945 JEFINED KECORD LIQUOR FROM PRQDREC 

90346 ALLOW AOD ANO DELETE 

90547 IDENTIFIER PROD-NAME 

90348 IDENTIFIER BRAND FROM PRNDeSIZE 





Figure 2—38. Complete Data Definition Processor Output Listing (Part 7 of 2) 
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50340 ITEM PYVPE FROM PROD-TYPE 
50350 ALLOW CHANGE 
90951 ITEM ON-WANOD 
9095? ALLOW CHANGE 
90353 ITEM UNIT FROM UNITUF-ISSUE 
30956 ALLOW CHANGE 
30355 ITEM COs? 
3039548 ALLOW CHANGE 
90957 SUPPLEMENT NUE-OUT-SUPP 
903568 FROM QUE-QUT 
90350 ASSUMES CONTROLLED 
303649 POINTER {S$ PROD-NAME, BRAND 
90361 ITEM DUESQUY FROM DUEQUT-TOTAL 
30362 ALLOW CHANGE 
390963 SUPPLEMENT DUB@IN-SUPP 
90366 FROM DUESIN 
90265 ASSUMES CONTROLLED 
90366 POINTER £$ PROD-NAME BRAND 
20267 ITEM VENOOR 
90368 ALLOW CHANGE 
3036¢ MUST ADD 
303970 ITEM DUE@IN FROM QUANSDUF@IN 
9097) ALLOW CHANGE 
90972 SUPPLEMENT VENDREC 
20973 FROM VENOREC 
90576 ASSUPES CONTROLLING 
903975 POINTER £8 VENNOR 
90976 ITEM VEND-NAME 
90977 1TEM VEND~ADOR 
THE FOCLAWIRG IS THE CIBNL DESCRIPTION OF THE DEFINES FILE SECHUMT 
v2 SECNYNT, 
eo0ea2evueceeweteteeoesoevee te BOeepeeevewe_eesveeegepe#e#eeetseeegyeeueueeeueev eawenene vee ermlelc etl hl rl ala ee 
e PEFINES RECORD eee oeeeeseeeveeneeeseeane senses Seep aeeeeezeanvneevee ene een ee 6 ee 
eeteoee#s#eset euseee pe &©BeOeepeeapeevoweeeteesvee Ceaesreaegegegeeeeeoe eueeoeeeeaestnneaeeeeae 
03 LIQJER 
0% PRUD-NMAME PIC xX¢LS), 
04 BRANO PIC x02), 
0% PTYPE PIC x(02}, 
04 MNeHatD PIC 9(02) 'SAGE 1S CIMPo4, 
0% Unit PIC x¢02), 
O* CST PIC 9(05)y99 USAGE IS COMP <3, 
0% DUJE-OUT PIC 9402) 'IS8GE 15 COMP oa, 
0* VENDUPF PIC 9(02) ‘ISAGE [§$ CUMPH4, 
64% Quel? PIC 9(02) SAGE [5 COMP 4, 
0% VEND-NAME PIC (20), 
0* VEND-ADOR PIC X35), 
@ THE JEFINER te CORD *ILL AUTOMATICALLY INCLUDE SNF STATUS BYTE FUR EACH ELEMENTARY ITEM DEFINED AROVE 
G $-LIQUOR, 
0% S=PRID-NAME PIC X, 
0% §=98RAND PIC X, 
0% S=BTYDE PIC X, 
0% S§-QN=-AND PIC X, 
0% S§-UNIT PIC X, 
0% §-COSs? PIC X, 
0% g$-DUE-O0UT PIC X, 
0¢ S=-VENDOR PIC X- 
04 §-QUE~IN PIC Ke 
04% S-VEND-NAME PIC X, 
0% S-VEND@ADSK PIC X, 
porTa MATA LEFINITIUN COFPLETE START @37928 FHA 639134 
Figure 2—38. Complete Data Definition Processor Output Listing (Part 2 of 2) 
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THE FOLLOWING 18 THE COROL DESCRIPTION OF DEFINES FILE 28. 
Cz PR. 

so «© #« @ @ @ @ @ @ he lh6UmfhlUD 

© DEFINED RECORD eee 

s s 


@ 
03 ZRAORBO 
O04 IRKOKO Pic 69408) USAGE 15 COMP-3. 
O04 ZRH DNR Pic) | 6ntOe). 
O4 ZRwL PIC x(102). 
O% 2Z2RZE)LEI Pic X(3IO be 
ZARIE ILE? Pic RC(30 Fe 
ZRIEILES Pic 8 6©Mt1308. 
ZRIEILE4 PIC xKI300. 
ZRIETLES ae ee oe lel a 
TRZEILESE Pic 8 KU3IOF. 
© THE OEFINED FECORD BILL AUTOMATICALLY INCLUDE ONE STATUS @YTE FOR CACM ELEMENTARY ITEM DEF INEO ABOVE 
O03 S-7R##DRO0- ; 
C4 f-7heH OKO PIC Be 
o4# -Z7RKOWR PIC Re 
o4 -7RNL PIC XxX. 
o4 -TAZE3LE 3 PIC Me 
C4 *Z7RZEILE2 PIC Me 
o4 *ZJRIZETLE3 PIC 1. 
O4 S-ZRZ2EILE4 Pic ¥. 
O4 S-7RZEILES PIC Ke 
OY CH-TRIELEE* PIC Ke 
Cé Cre2ies 
s @ s e a e e @ a e 
© DEFINED RECORD « « 
e s e e e 6 s a e e e 
O02 CH-2F 4DFRO 
cH zRK 00 Pic) | 6©9tas) USAGE IS COMP-32, 
04% ZRKOWR Pic rtcCaete 
04 ZRwWL Pic 8 6©KIO2Z1. 
C4 2K OF0 Pic $05? USAGE 16 COmMP-3, 
OW 2Z2RTIEILEF PIC 8 xt30%. 
© TME DEFINED RECORD WILL AUTOMATICALLY INCLUDE ONE STATUS BYTE FOR EACH ELEMENTARY ITEM DEFINED ABOVE 
O03 S+CH-Z7RADRBO. 
S-7hkF OFO PIC He 
S<-7RKONK PIC Re 
©-2ANL ; PIC Xe 
S-7RE ORO PIC Me 
S-7RTZE ILE 1 PIC Re 


A UR UA AA 


OFts CEFINITION COMPLE TE START £49517 END £19522 





Figure 2—39. Last Page of Data Definition Processor Listing Showing COBOL Description of a Defined File and a Subfile 


2.5.4. Error Processing by Data Definition Processor 


In processing your input, the data definition processor acts like a COBOL compiler; it subjects 
the entire input to scrutiny for syntactical errors and issues diagnostics. 


The data definition processor applies the rules of COBOL to the data division of the input 
and issues COBOL diagnostics for this division. The COBOL reserved word list applies to 
the data division of the input to the data definition processor as well. When processing the 
definition division, however, the data definition processor applies not only the appropriate 
standard COBOL rules, but also rules of its own. (See 2.3.1.) Detected violations of these 
rules result in the issuance of diagnostics from a set unique to the data definition 
processor. These diagnostics are listed in Table 2-2. 


Each diagnostic message contains the processor-generated line number on which the 
error occurred, the diagnostic severity code, the diagnostic number, and the diagnostic 
message text, in that order. 













Table 2—-2. Compilation Time Diagnostics Unique to the IMS 90 Data Definition Processor (Part 1 of 2) 


pout M 
“io maine em 
Reason 


—SUSPEND CHECKING INVALID SOURCE 
STATEMENTS ON THIS LINE. 


—RESUME CHECKING SOURCE STATEMENTS 
ON THIS LINE. 





REFERENCE TO insert INVALID 


DEFINITION 1S TOO LARGE 






CHANGE TO NEUTRAL SUPPLEMENT IS 
ILLEGAL. 






CHANGE TO CONTROLLING eh Sa LL 
iS ILLEGAL. 



























Beginning at this source line, 
the data definition processor 

does not recognize source input 
as data definition language. 


Having previously issued diagnostic 
139, the data definition processor 
again recognizes source input as 
data definition language. 


Self-explanatory 







The length of the data definition 
record exceeds the blocksize specified 
for the NAMEREC file. 


The processor has encountered the 
ALLOW CHANGE option specified in 

a supplement for which no ROLE 

IN UPDATE is specified, or whose 
update ROLE is specified as NEUTRAL. 


The processor has encountered the 
ALLOW CHANGE option specified in a 
supplement whose ROLE IN UPDATE 
is specified as CONTROLLING. 

















Explanation 


No validity checking for 
syntax of data definition 
source statements occurs 
until some succeeding 

statement is recognized. 


Error processing continues; 
beginning with this source 
line. 


Refer to 2.3 for the rules for each 
statement. 


Biock size for the NAMEREC file 
specified with the NBLK keyword 
parameter of the IMSCONF jproc 
or the BLKSZE parameter of the 
ZPH#NRU utility. It ranges 
between 1024 and 12,800 bytes 


but most not exceed disk track size. 


if the ALLOW CHANGE option is 
specified for an item, its 

ROLE IN UPDATE must be 
CONTROLLED. 


If the ALLOW CHANGE option is 
specified for an item, its 

ROLE IN UPDATE must be 
CONTROLLED. 































if preceded by another 
diagnostic for the same 
line number, recovery for 
that diagnostic will 

usually suffice, but the 
remainder of this line 
might contain another 
error. Otherwise, this 

line contains an error that 
that is not embedded ina 
recognized statement type. 















None required. All lines 
for which validity checking 
was skipped should be 
scanned for possible 
error, before recompiling. 















Correct the data definition 
and recompile. 











Reduce size of the data defi- 
nition record and recompile. 
The line number indicated is 
the one which caused the over- 
flow. 



























Alternatively, specify a larger 
block size for the NAMEREC 
file and reconfigure. 





















Correct the data definition 
and recompile. Your action 
Program logic may also 
require revision, 





















Correct the data definition 
and recompile. Your action 
program logic may also 
require revision. 









SNOILVOMNddV 06 SWI 





L ‘Ady 7L98-d/N 


€/SO OWAINN AUHadS 


LZ-¢ 


Message 
Number 
163 Cc 


167 





















Table 2—2. Compilation Time Diagnostics Unique to the IMS 90 Data Definition Processor (Part 2 of 2) 





ADD TO NEUTRAL SUPPLEMENT IS 
ILLEGAL. 


ADO TO CONTROLLING SUPPLEMENT 
(S ILLEGAL. 


CANNOT ADD OR DELETE REPEATING 
GROUP. 


SEE CONSOLE FOR DMXX 













CANNOT ADD OR DELETE CONTROL BREAK. 




















The processor has encountered a 
MUST ADD statement specified for 

a supplement for which no update 

role is specified or for which 

ASSUMES NEUTRAL ROLE IN UPDATE 
is specified. 


The processor has encounterd a 
MUST ADD statement specified in a 
supplement for which ASSUMES 
CONTROLLING ROLE IN UPDATE is 
specified. 


The processor has encountered one of 
three options of the ALLOW ADD AND 
DELETE statement specified for a 
defined record for which a FROM 
CONTROL BREAK statement is also 
specified. 


The processor has encountered one 
of the three options of the ALLOW 
ADD AND DELETE statement specified 
for a defined record for which a FROM 
REPEATING GROUP statement has 
been specified. | 


OS/3 ISAM has issued a numbered data 
management error message to the 
system console, reflecting an error 
detected during processing of the 
NAMEREC file by the data definition 
processor. 

















If the MUST ADD option is 
specified for an item, its 
ROLE IN UPDATE must be 
CONTROLLED. 


The ALLOW ADD AND DELETE 
statement cannot be specified 

for a defined record for 

which FROM CONTROL BREAK 
is also specified. 


Same as 161. 















Same as°161. 


Same as 161. 


According to the nature of 
the error detected or 
reported to ISAM. Refer to 
the OS/3 system messages 
operator/programmer 
reference, UP-8076 (current 
version) and to the data 
management user guide, 
UP-8068 or programmer 
reference, UP-8159 (current 
versions). 












The ALLOW ADD AND DELETE 
statement cannot be specified 

for a defined record for 

which FROM REPEATING GROUP 
is also specified. 

















None. The actual OS/3 data 
management message number, 
the prefix of which is “DM”, 
will appear at the system 
console and on the console 
output printer (COP) sheet 
for the run. 




























L A8¥ VL9O8-dN 
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®@ Definitions of diagnostic severity are as follows: 
a P (precautionary) 


No source language error detected, but an unusual or potentially undesirable 
condition noted by the data definition processor. 


# C (changed) 


A character, word, clause, entry, or statement in the source program is omitted or 
used incorrectly. To compensate for the error, the item has been changed by the data 
definition processor to avoid its deletion and reduce the probability of error 
propagation. A data definition record is not created. 


# U (uncorrectable) 


A source language error detected causing the data definition processor to delete a 
character, word, clause, entry, or statement from the source program. The compilation 
continues, but other errors may result because of the deleted item. A data definition 
record is not created. 


= S$ (compiler restriction exceeded) 


The compilation continues but, to generate code for the excessive items, a 
® recompilation is necessary after source program modification or with more storage 
assigned to the compiler. 


Figure 2-40 shows the last page of output from an unsuccessful run of the data definition 
processor, during which it was not possible to construct the desired data definition record 
and error testing was not completed. The diagnostic messages listed happen to be limited 
to the set that is unique to the data definition processor; however, COBOL diagnostics 
would be listed in the same manner and location. 


DOPT3 COMPILED &8Y UNIVAC 08/3 DATA DEFINITION PROCESSOR VER Oave 75709710 TIME 2 55 506 
LINE® SVC ERROR - JIAGNOSTIC MESSAGE PAGE 00003 


000695 163 ADO TO NEUTRAL SUPPLEMENT IS ILLEGAL 


¢ 
0007! Cc 163 CHANGE TO NEUTRAL SUPPLEMENT 15 ILLEGAL. 
U 


00077 160 DEFINITION IS TOO LARGE. 


THE OATA DEFINITION RECORD COULG NOT BE CREATED. ERROR TESTING WAS NOT COMPLETED. PLEASE, CORRECY ANDO RECOMPILE. 
DOPT 3 DATA DEFINITION COMPLETE START 2 55 $0 ENO 2 $6 23 





Figure 2-40. Last Page of Data Definition Processor Listing from Unsuccessful Run 
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3. User-Written Action Programs 


3.1. DESCRIPTION | 


Action programs operate under the application management component of IMS 90; they 
process input messages and generate output messages. Action programs operate as 
subprograms to the configured IMS 90 online program. Some action programs are 
provided as a standard part of IMS 90. For example, the uniform inquiry update element 
(UNIQUE) is a series of action programs. 


You can also write your own programs for applications that cannot be implemented with 
UNIQUE. Some applications require more extensive data validation for update operations 
than UNIQUE can provide. Other applications require special output formats. These 
requirements and others are accommodated within the general framework provided for 
user-written action programs. This section describes the framework within which you 
write your own action programs. 


Action programs can be written in COBOL, RPG Il, or BAL. The current versions of the 
following OS/3 documents can be referenced when preparing these programs: 


# extended COBOL supplementary reference, UP-8059 


1974 American National Standard COBOL programmer reference, UP-8613 
= report program generator (RPG Il) programmer reference, UP-8044 
= assembler programmer reference, UP-8227 


If your action programs access a DMS 90 data base, see the current versions of the 
following manuals: 


=» IMS 90/DMS 90 interface user guide/programmer reference, UP-8748 
= DMS 90 data description language user guide/programmer reference, UP-8022 
=» DMS 90 data manipulation language user guide/programmer reference, UP-8036 


COBOL and BAL action programs also can call user-written resident subprograms. 
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3.1.1. Action Program Environment ® 


An action program is scheduled for execution either because an input message is received 
that must be processed by the action program or because one action program has 
designated another action program as its immediate successor. In either situation, when 
execution of the action begins, a standard environment exists in which it carries out its 
processing. The environment is shown in Figure 3-1. 


The environment consists of certain main storage areas, each of which has a specialized 
function, and a set of standard interfaces to IMS 90 for all file input/output, message 
output, and program termination requests. 


Because of the requirement that action programs must be at least serially reusable, no |/O 
areas or other main storage areas with varying contents can be compiled or assembled 
into an action program. When application management activates an action to process an 
input message, the variable main storage areas that are required are dynamically allocated 
from the IMS 90 main storage pool. Accordingly, when the action scheduling component 
of application management calls the action program, it passes a list of addresses of the 
dynamically allocated areas. 


Areas Dynamically Atliocated 
by Action Scheduling 











Input Message Area 
contains input message 


at action program ; 
initiation & 


Program Information 
Block used by action 
program to communicate 
internally with IMS 90 


{MS 90 Components Calied 
by Action Program 


ACTION 
SCHEDULING 
FILE 
MANAGEMENT 






PROGRAM 
INFORMATION 
BLOCK 






Action Program 
Initiation and 
Termination 


Work Area used for file 


1/0 logical record areas 
and working storage 








All User File ACTION PROGRAM 


1/O Functions 










t_2 Optional 





Defined Record Area on 
used by defined record | 
management if defined 


files are accessed 


Message - ian ora renee i 
Output CONTROL 7 
I eo} CONTINUITY i Continuity Data Area 
! ; DATA AREA : used in dialog transactions 
pal I i 
1, ! Mf seca eh ce Sele pe J 
| 
! == 1 
) ! | t Qutput Message Area 
{ | ' OUTPUT ! contains output message 
—> MESSAGE at action program 
LEGEND: | termination 
I Se nee ae gee mage ae OR 
C—] Required : 
t 
t 
i 
t 
L 


isa Cannot be written into by user program 


Figure 3—1. Action Program Environment 
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Two main storage areas are always present: the program information block and the input 
message area. The program information block is used to communicate information 
between IMS 90 functions and an action program at initiation, after |/O functions, and at 
termination. The input message area contains the input message that caused HG action 
program to be Sener: 


The work area, output message area, continuity data area, and defined record area are 
optional. The work area is a general-purpose area used for working storage, logical record 
areas during file I/O functions, or output messages sent explicitly. The output message 
area normally is used to build an output message that is sent to the originating terminal 
when the action terminates. The continuity data area is used to pass data from one action 
to another. It is saved by action scheduling at the termination of one action and restored 
upon initiation of the next action in a dialog. The defined record area is used by defined 
record management if the action program accesses defined records. It cannot be written 
into by the user program. 


The choice of the specialized main storage areas that are to be associated with a given 
action program, and what their sizes are to be, is made at configuration time and, in some 
cases, by the immediately preceding action at execution time. 

All file |/O, explicit message output, and program termination requests made by an action 
program must be made through IMS 90 function calls. Transfer of control to a user-written 
resident Subprogram also is made in this manner. 


3.1.2. Transaction Structures 


A transaction is one action or a sequence of related actions. A-simple transaction consists 
of one action; a dialog transaction consists of two or more related actions. 


The structure of a transaction depends on whether that transaction is performed by a 
single action program, by more than one action program processing a single action, or by 
several actions dynamically sequenced. Transaction structures differ according to the type 
of termination specified in the action programs that process the transaction. There are four 
types of termination: 

1. Normal 

2. External succession 

3. Immediate internal succession 


4. Delayed internal succession 


The type of action program termination is specified in the termination indicator of the 
program information block (PIB). (See 3.6.1.) 
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3.1.2.1. Simple Transaction 


The structure of a simple transaction is shown in Figure 3-2. A message is input from a 
terminal and contains a transaction code as the first one to five characters. The 
transaction code is used to look up the name of the action program that is to process the 
input message. For each transaction code, there can be only one corresponding action 
program. More than one transaction code, however, can designate the same action 
program. Transaction codes must be defined to IMS 90 at configuration time. 


The input messge is placed on a queue for the action program until scheduling occurs. The 
scheduling process consists of allocating the main storage areas required by the action 
program from the IMS 90 main storage pool, loading the action program from a disk library 
file if it is not already resident, moving the input message from the queue into the input 
message area, and passing control to the action program. Because Figure 3-2 is a simple 
transaction with a single action program, the use of the continuity data area does not 


apply. 






INPUT OF MESSAGE 


QUEUEING BASED ON 
TRANSACTION CODE 


RESOURCES 
ALLOCATED 


EXECUTION OF 
ACTION PROGRAM 1 





“© NORMAL 
TRANSACTION 
TERMINATION 
SPECIFIED 

RESOURCES DEALLOCATED 










OUTPUT OF MESSAGE 


Figure 3—2. Simple Transaction 
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The action program accesses files by calling on IMS 90 file management to request that 
the logical or defined records be placed in the work area. The text of the output message 
is built in. the output message area. The action program then requests a normal 
transaction termination. The type of termination is specified in the PIB. 


This sequence of events: is called an action within IMS 90. It always begins with the input 
of a message and ends with the output of a response. The simple transaction in Figure 
3-2 consists of a single action, performed by a single action program. (An action also can 
be performed by more than one action program as shown in Figure 3-4.) 


3.1.2.2. External Succession 


IMS 90 can establish a relationship between two or more successive actions. A 
transaction that makes use of this relationship is called a dialog transaction, which can 
consist of an arbitrary number of actions. The dialog transaction in Figure 3-3 consists of 
two actions. 







INPUT OF MESSAGE 
1 







INPUT OF MESSAGE 
2 


QUEUEING BASED ON 
TRANSACTION CODE 


QUEUEING BASED ON 
SUCCESSOR ID 


ALLOCATION OF 
RESOURCES 


ALLOCATION OF 
RESOURCES 
RESTORATION OF 


CONTINUITY DATA 
EXECUTION OF pea 


ACTION PROGRAM 1 





~€EXTERNAL 
SUCCESSION EXECUTION OF 


ACTION PROGRAM 2 
DEALLOCATION OF SPECIFIED 


RESOURCES NORMAL 


SAVING OF TRANSACTION 
CONTINUITY DATA TERMINATION 


SPECIFIED 





DEALLOCATION OF 
RESOURCES 










OUTPUT OF 
MESSAGE 1 










OUTPUT OF 
MESSAGE 2 


Figure 3—3. Dialog Transaction, External Succession 
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The example in Figure 3-3 is the same as Figure 3-2 up to the termination of action 
program 1. The action program in Figure 3-3 specifies in the PIB the name of another 
action as its successor and designates the type of termination as external succession. (The 
name of an action is the same as the name of the first action program in that action.) The 
deallocation of resources occurs as in Figure 3-2 except for the continuity data area. The 
contents of the continuity data area are saved in the continuity data file before the area is 
released. When input message 2 is received, it is queued for the action designated as the 
external successor. Input message 2 is not tested for a transaction code. When the new 
action is scheduled, the saved continuity data record is read into the new continuity data 
area for action program 2. 


How is the dialog transaction (Figure 3-3) different from two successive simple 
transactions like the one in Figure 3-2? First, in Figure 3-3, input message 2 does not 
contain a transaction code. It is immediately associated with the succeeding action 
designated by action program 1. In Figure 3-2, if a second simple transaction follows the 
one shown, the input message must contain a transaction code. Second, in Figure 3-3, a 
continuity data area is used to carry information from the first action to the second action. 
The action programs need not intervene to provide the continuity. In Figure 3-2, if a 
second simple transaction follows the one shown, information from the first transaction 
cannot be passed to the second (other than through the second input message or through 
a user data file). | 


The action program structures shown in Figures 3-2 and 3-3 should meet the 
requirements of most applications. For applications that require greater flexibility in the 
allocation of resources during an action, there are two additional types of action program 
succession - immediate internal succession and delayed internal succession. 


3.1.2.3. Immediate Internal Succession 


The processing within an action may consist of the execution of two or more action 
programs in sequence. Figure 3-4 illustrates the execution of two action programs in a 
single action. The process is the same as in Figure 3-2 except when action program 1 
terminates. In this situation, the action program specifies in the program information block 
the name of another action program and designates the type of information as immediate 
internal succession. This effectively provides an overlay capability. 


Action program 1 is released, but the allocated main storage areas are held and no 
message Is output. Action program 2 is then acquired; it is given control and access to the 
same main storage areas (program information block, input message area, work area, 
output message area, continuity data area, and defined record area) as its predecessor. 
Action program 2 completes the processing for the action and terminates. The normal 
transaction termination results in the deallocation of resources and the output of the 
message. 


Because immediate internal succession involves only one action, all files accessed by the 
successor program must be available when the initial program is executed. This means 
that they must be specified in the configurator ACTION section for that action. 
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ACQUISITION OF 
ACTION PROGRAM 2 


INPUT OF MESSAGE 


QUEUEING BASED ON 
TRANSACTION CODE 


EXECUTION OF 


ALLOCATION OF ACTION PROGRAM 2 


RESOURCES 





“& NORMAL 
TRANSACTION 
TERMINATION 


PE 
DEALLOCATION OF peer 


EXECUTION OF RESOURCES 


ACTION PROGRAM 1 





“= IMMEDIATE 








INTERNAL 
er aurea 
RELEASE OF OF 
ACTION PROGRAM 1 MESSAGE 





Figure 3—4. Immediate Internal Succession 


3.1.2.4. Delayed Internal Succession 


In some situations, main storage areas as well as action programs must be changed 
during the processing of a message. This can be the case, for example, when some. 
exceptional condition that is encountered only infrequently in an input message requires a 
different program with a much larger work area to carry out the processing. 


Delayed internal succession can be used to effect this dynamic change. 


Delayed internal succession also can be used to minimize the I/O area requirements for 
an action. During the scheduling of an action, IMS 90 must dynamically allocate |/O areas 
for all files referenced in the action. If many files are accessed in processing a message, 
some frequently, some rarely, then the frequently accessed files should be specified at 
configuration time for one action, and all of the other files should be specified for another 
action. 


The first action should be scheduled to process all messages from the terminal. If in 
processing a message it encounters an exceptional condition that requires a rarely 
accessed file, the first action should terminate and designate the second action as its 
delayed internal successor. 
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Delayed internal succession provides the only example of an action that apparently does 
not include both an input message and an output message. Actually, the first action builds 
an output message in the output message area, but this message is not sent to the 
Originating terminal. Instead, it is queued as the input message to the second action. As a 
result, the second action does not require the input of a message from the terminal. In this 
type of structure, even though there is apparently only one input message and one output 
message, internally there are two separate actions, each with an input message and 
Output message. | 


Note that delayed internal succession when used in single-thread IMS 90 behaves like 
immediate internal succession; that is, the output message is not queued as an input 
message to the next action but, instead, is passed immediately to the successor action 
program. 


Figure 3-5 shows a transaction that employs delayed internal succession. This example is 
the same as Figure 3-2 up to the termination of action 1. The action program specifies in 
the PIB the name of another action as its successor and designates the type of information 
as delayed internal succession. The deallocation of resources occurs as in the first action 
in Figure 3-3. The output message of action 1, however, is not output to a terminal; it is 
queued as an input message to action 2. | 


When the scheduling occurs for action 2, the output message from the previous action is 


provided as the input message. In addition, the continuity data record developed in action 
1 is made available in the new continuity data area for action 2. 
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Figure 3—5. Delayed Internal Succession 
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3.1.2.5. Combination Structures 





Combinations of the various types of action program succession leads to great flexibility in 
the structuring of transactions. There are basically no limitations to the ways in which 
types of succession can be combined. For example, immediate internal succession, delayed 
internal succession, and, finally, external succession all can be specified in turn. 


The capability of specifying the successor identification dynamically in the PIB (versus 
prespecifying the same identification at configuration time) enables a program to develop a 
dynamic transaction structure. The structure is limited to one level of control; that ts, at 
any given time, only one action program can process a given transaction. The processing, 
however, can take an arbitrary number of paths. Figure 3-6 is an example of dynamic 
transaction structure. 
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ACTION ACTION ACTION 


PROGRAM 6 


PROGRAM 7 PROGRAM 8 





TRANSACTION 
TERMINATION 3wTUT TTT 
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Connecting lines represent immediate internal, delayed internal, or external succession, or any combination of them. 


Figure 3—6. Dynamic Transaction Structure 
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3.1.3. Action Program Reusability 


Action programs can be written as serially reusable, reentrant (BAL only), or sharable 
(COBOL only). The type of reusability, as well as other attributes of action programs, must 
be defined to IMS 90 at configuration time. Programming considerations for program 
reusability are noted where applicable in the discussions on COBOL, RPG Il, and BAL 
action programs. The type of reusability has little effect on processing speed in a single- 
thread environment; however, for effective use of multithread IMS 90, action programs 
should be either shared code (COBOL) or reentrant (BAL). (RPG Il programs are serially 
reusable only.) By using shared code or reentrant action programs in a multithread 
environment, you can avoid deadlock. Action programs written in either shared code or 
reentrant code avoid the case where a serially reusable program with outstanding record 
or file locks cannot be scheduled for execution. (See 3.8.7.2 for a detailed discussion of 
deadlock.) 


3.1.4. Device Independent Control Expressions (DICE) 


User-written action programs can use either remote device hardware control characters or 
device independent control expressions (DICE) to format input and output messages via 
function codes that position the cursor, control carriage return, control forms, control line, 
feed line, and erase the screen. 


ICAM automatically inserts DICE sequences into input messages. One reason for their use 
in input messages is to compare the input message with a previous output message for 
validation. For output messages, your action program must move the 4-byte DICE 
sequence to the output message area. 


In most cases, the user configures the removal of DICE sequences from input messages by 
specifying EDIT=tablename or EDIT=c in the configurator ACTION section or by omitting 
the EDIT parameter. If EDIT=NONE is specified, the DICE sequences are not removed. 


The DICE sequence consists of the select character (10,,¢), a hexadecimal function code, 
and two hexadecimal coordinates, the first representing a row and the second, a column 
on the terminal. To set the function code, you choose the hexadecimal value equivalent to 
the operation required to format a message. 


The COBOL action programmer can specify DICE sequence values in the working-storage 
section of his action program or, if certain DICE sequences are used frequently, he may 
file his description in a COBOL copy library to be called into the action program via the 
COPY statement in his action program’s working-storage section. (See Figures 3-27 and 
3-28.) 


The action programmer using 1968 American National Standard COBOL must indicate the 
hexadecimal values for the DICE sequences by supplying their multipunch equivalents. 
(See Figures 3-27 and 3-28 for examples that use multipunch written to 1968 standards.) 
The 1974 COBOL standards permit the action programmer to use the hexadecimal DICE 
values directly in the action program. The following examples illustrate three possible 
applications of hexadecimal DICE values that conform to 1974 standards. 
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© Example 1: 


61 DICE 
O03 FIELD-1 PIC X 
93 FIELD-2 PIC X. 
93 FIELD-3 PIC X. 
03 FIELD-4 PIC X.. 
MOVE ='16' TO FIELD-1. 
MOVE ='03' TO FIELD-2. 
MOVE =‘01' TO FIELD-3. 
MOVE ='@1' TO FIELD-4. 


Example 2: 


863 DICE PIC X(4). 
MOVE =‘'188380161' TO DICE. 


Example 3: 


77 DICE PIC X(4) VALUE ='1693901861' 





In a BAL action program you can use DICE macros provided by ICAM to generate DICE 
sequences inline. For an example of use of the ICAM procedure, ZO#POSC, to generate 
inline the DICE sequence for clearing the current line and repositioning of the cursor, see 
Figure 3-38. 





DICE is a more convenient method of writing COBOL and BAL action programs than using 
the device dependent editing and control codes peculiar to specific terminals. DICE usage 
and DICE codes are described in Appendix E. 
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3.2. COBOL ACTION PROGRAMS 
The basic format of a COBOL action program is: 


IDENTIFICATION DIVISION. 

PROGRAM-ID. program-name. 

(Any optional entry may be specified. ) 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. 

OBJECT-COMPUTER. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

(Optional. May be used only to contain constants. ) 
LINKAGE SECTION. 

(Describes each area that is referenced in the procedure division ENTRY 


statement. ) 
01 PROGRAM-1INFORMATION-BLOCK 


O01 INPUT-MESSAGE-AREA 


[01 WORK-AREA 
[01 OUTPUT-MESSAGE-AREA 


[01 CONTINUITY-DATA-AREA] ]}] 


PROCEDURE DIVISION USING PROGRAM-INFORMATION-BLOCK INPUT-MESSAGE-AREA 
[WORK-AREA[OUTPUT-MESSAGE -AREA[CONTINUITY-DATA-AREA]]]. 
3.2.1. COBOL Action Program Sharability 


A COBOL action program can be compiled with or without the shared code parameter of 
the extended COBOL compiler. The shared code parameter format for American National 
Standard 1968 COBOL is: 


// PARAM OUT=(M) 


The shared code parameter format for American National Standard 1974 COBOL is: 


// PARAM IMSCOD=YES 


Use of this parameter allows the compiler to check the program for conformance to IMS 
90 language restrictions and issue appropriate diagnostics at compile time. Using this 
option in combination with the TYPE=SHR and SHRDSIZE parameters of the configurator 
allows the programs to be run as reentrant under multithread IMS 90. 
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3.2.2. COBOL Language Restrictions 


Use of certain COBOL language elements is restricted in action programs. The following 
restrictions enable programs to be compiled as either sharable or serially reusable: 


IDENTIFICATION DIVISION 


Do not use a function key (F#nn) as the PROGRAM-ID name, because the COBOL 
compiler treats the # symbol as invalid. If you want to use a function key to identify 
the load module, supply a valid PROGRAM-ID name in the identification division and 
then include a LOADM statement with FH#nn as the load module name at link edit 
time. 


CONFIGURATION SECTION 
Special names must be omitted. 
INPUT-OUTPUT SECTION 


The input-output section must be omitted because all I/O is performed by IMS 90 file 
management. 


FILE SECTION 
The file section must be omitted. 
WORKING-STORAGE SECTION 


The working-storage section !s optional. When present, it is used only to contain 
constants; that is, all elementary items must be described with a VALUE clause. 
When you compile your action program with the shared-code parameter, COBOL flags 
only procedure statements that move data to the working-storage section. If the 
program does change these values, it must not depend upon their original value 
during a subsequent execution.* | 


PROCEDURE DIVISION 


A DECLARATIVE clause may not be included. Debugging language (EXHIBIT, TRACE) 
and segmentation (priority numbers, SEGMENT-LIMIT clause) are prohibited. 


“If the action program is to be compiled only under the serially reusable option, data items within the working-storage 
section may be changed in value during execution. However, the execution of such a program must not depend upon 
values left in working storage by a previous execution. 
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@& The following COBOL verbs, clauses, and sections are illegal in action programs. When 
compiling with the 7/ PARAM OUT=(M) or // PARAM IMSCOB=YES options, the 
following language elements are diagnosed and deleted from the program by the compiler: 


ACCEPT : OPEN SYSCHAN-t 
ALTER READ SYSCOM 
CLOSE READY TRACE SYSCONSOLE 
DECLARATIVE SECTIO RELEASE SYSDATE 
DISPLAY 7 RESET TRACE SYSERR [-m] 
ENTRY RETURN SYSLST 
EXHIBIT REWRITE SYSSWCH 
EXIT- PROGRAM SEEK SYSTIME 
FILE SECTION | SEGMENT-LIMIT WRITE 
INPUT-OUTPUT SECTION SORT 
INSERT | | STOP 


The following verbs must not have working-storage items as receiving operands. If the 
shared code parameter was used upon detection of this condition, the compiler generates 
the statement and issues a precautionary diagnostic. 


ADD : PERFORM (VARYING option) 
COMPUTE SEARCH (VARYING option) 
DIVIDE SET 

| EXAMINE (REPLACING option) SUBTRACT 

& MOVE TRANSFORM 
MULTIPLY | 


Normally, execution-time errors result in a CE error message and program termination. In 
an action program, execution-time errors result in a program check interrupt and a 
snapshot dump of the action program with the address of the CE message in register 1. 
The action program is terminated. For further details, refer to 3.8.6.3. 


Under multithread IMS 90, for the COBOL object program to be reentrant at CALL 
interrupts, the volatile work area used by the program must be saved and restored by the 
IMS 90 system. The size of the area (which varies between programs) is displayed in 
decimal by the printer immediately prior to the COBOL COMPILATION COMPLETE 
message. The message reads: 


SHARED CODE VOLATILE DATA AREA = nnnn BYTES 


This size is used in computing the SHRDSIZE parameter in the IMS 90 configurator. This 
message and the reentrant capability of the program is available only when the program its 
compiled with the COBOL shared-code parameter. 
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3.2.3. Linkage Section 


The linkage section is required. It describes areas that are made available to an action 
program when it is called by action scheduling to begin or continue the processing of an 
input message (Figure 3-1). The areas are allocated by action scheduling based on the 
information contained in the action control table (specified at configuration time) and 
parameters set in the program information block by the final action program in the 
preceding action (if any). The contents of areas referenced through the linkage section can 
be modified by an action program as required in the processing of an action. For each area 
referenced in the USING list at the point of entry to the action program, there must be a 
corresponding 77 or O1 level data description in the linkage section. 


The main storage areas described in the linkage section always include the program 
information block (PIB) and input message area (IMA) and may also include a work area 
(WA), an output message area (OMA), and a continuity data area (CDA). The defined 
record area is never described in the linkage section; it is used by defined record 
management (DRM) when defined files are accessed and cannot be written into by the 
action program. Main storage areas and their uses are discussed in 3.6. 


3.2.4. Procedure Division 


The procedure division header with the USING statement lists the main storage areas 
used by a COBOL action program. The parameters of the USING list are positional and 
must be coded in the prescribed order, taking care to code a dummy parameter to maintain 
this order where an optional parameter is omitted. For example, if the WORK-AREA and 
CONTINUITY-DATA-AREA parameters are not required, the procedure division starts with 
the following statement: 


PROCEDURE DIVISION USING PROGRAM- INFORMATION - BLOCK INPUT-MESSAGE-AREA D 
OUTPUT-MESSAGE-AREA. 


where: 


D 
Is a data name used as a dummy parameter for WORK-AREA to maintain the 
proper position for OUTPUT-MESSAGE-AREA. The CONTINUITY-DATA-AREA 
parameter is omitted entirely. The D must also have a corresponding 77 or O1 
level entry in the linkage section. 


A basic rule that must be followed in writing the procedure division statements of a 
COBOL action program is that no I/O operations are specified using standard COBOL !/O 
verbs. All file operations must be requested through IMS 90 file management, using the 
CALL statement. (See 3.7.) While message input and output are generally handled 
implicitly via the input and output message areas, certain message output operations can 
be performed by making explicit requests to internal message control. (See 3.8.) These and 
other requests to IMS 90 also are made by means of the CALL statement. The basic 
format of the CALL statement as used in COBOL action programs is: 


CALL function-name [USING data-name... ] 
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@ where: 


function-name 


Is the name of an IMS 90 function. The IMS 90 functions are GET, GETUP, 
UNLOCK, SNAP, SUBPROG, GETLOAD, SETLOAD, PUT, DELETE, INSERT, SETL, 
ESETL, FREE, SEND, and RETURN. Function names must be enclosed by single 
quotes. 


data-name 
Is the name of an item defined in the working-storage section or linkage section. 
The level number associated with each data name need not be O1 or 77. 
However, if a dataname at a level other than O71 or 77 Is given in the USING list, 
a precautionary diagnostic message (166) is printed for the statement by the 
COBOL compiler. This message is ignored. 


The CALL statement is preceded by an ENTER LINKAGE statement and followed by an 
ENTER COBOL statement. When a function is requested of IMS 90, the function is always 
carried to completion before control is returned to the statement following the CALL 
statement. Therefore, only one request can be outstanding for a given action at a given 
time. 


Program termination is requested by means of the RETURN function, whose format is: 


CALL ‘RETURN’ 


The CALL RETURN statement must be present at least once in an action program. The 
execution of this function results in the return of control to action scheduling and 
termination of the action program. The EXIT PROGRAM or RETURN statement must not be 
used for this purpose. When a COBOL action program is compiled without the PARAM 
OQUT=(M) statement, a diagnostic message is issued by the compiler because of the 
absence of an EXIT PROGRAM or RETURN statement. This diagnostic should be ignored. 


3.3. RPG Il ACTION PROGRAMS 


An RPG Il action program is distinguished from a usual RPG Ii program by the letter A in 
column 74 of the RPG II control card specifications form. In this way, the RPG II compiler 
generates an RPG Il program that interfaces with IMS 90 instead of data management. 


RPG Il action programs operate under the application management component of IMS 90 
to process input messages and generate output messages. These programs must be 
written so that they are serially reusable. After each execution of an action program, RPG 
ll resets all indicators and internal switches. Therefore, the programmer must reset all 
fields to their original values before the action program is executed again. All file 1/O 
requests are handled by IMS 90. RPG Il action programs are compiled and linked offline. 
The sample RPG Il action program, LSTLIM (see Appendix C), provides a detailed 
explanation of this entire process. Users should be familiar with the current version of the 
@ RPG il user guide, UP-8067. 
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3.3.1. IMS 90/RPG Il Interface Areas @ 


Four defined interface areas are used for control and communication of data between IMS 
90 and RPG II action programs: 


1. Input message area (IMA) 

2. Program information block (PIB) 
3. Output message area (OMA) 

4. Continuity data area (CDA) 


Unlike COBOL action programs, RPG Il action programs do not use the work area. Use of 
the four interface areas depends upon the requirements of the RPG Il action program. 


If the action program needs to reference a field in any of the IMS 90 interface areas, the 
interface area name preceded by a single asterisk (*) must be indicated as the device 
name in columns 40-46 of the RPG Il file description specifications form (e.g., “IMA, * 
OMA, etc.). (See Figure 3-7.) It is important to remember in referencing all four data 
interface areas to reference only those fields within the interface areas that your RPG Il 
action program actually use; otherwise, the field will be flagged as unreferenced in your 
RPG Il program. 


3.3.1.1. Input Message Area (IMA) & 


The IMA consists of a 16-byte control header plus the input message received from a 
terminal. The size of the IMA is, therefore, the input message length plus 16 bytes for the 
IMS 90 header information. In an RPG II action program, the IMA is defined as an input 
file on the file specifications form (columns 7-14) and the fields within the IMA are 
described on the input format specifications form (columns 44-58). In addition, the INSIZE 
parameter in the ACTION section of the IMS 90 configuration must specify the total IMA 
size used by an RPG Il action program. 


Following normal RPG II input specification rules for the IMA header, you do not define 
fields not required by your action program; however, you must allow the first 16 bytes of 
the IMA for the header and start the first input message character in position 17. Table 
3-1 is a summary of required entries defining the IMA on the file description 
specifications form. 
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Table 3—1. Summary of Required Entries for File Description Specifications Form 

















































User- 
Specified et File | 
split File Name | iis Be Designation : blip F Piao Length | mexics Name | 
oo (Columns 7-14) | ‘Column 1 (Column 16) oma olumns 24—27) | (Columns 40—46) 
See Note. | 


a CE CO 
a "| 
1,U,or O P,S, D, or data size *CDA 
| blank 


Any user file name can be specified but must begin with an alphabetic character and must not exceed seven characters. 








NOTE: 


3.3.1.2. Program Information Block (PIB) 


The PIB is used to pass control information between IMS 90 and the user action program. 
it is a predefined 48-byte area. 


Use of the PIB in an RPG Il action program is optional. RPG Il automatically performs the 
following PIB functions whether a PIB is or is not defined in an RPG Il action program: 


we RPG Il checks the status code returned after each 1/O request. When an error 
condition exists, RPG Il sets the HO indicator on and places the error status code into 
the *ERROR field. These error codes are shown in the system messages 
programmer/operator reference, UP-8076 (current version). 


a RPG II sets the abnormal termination code ‘S’ in the TERMINATION- INDICATOR of the 
PIB if the user does not set the HO indicator off by the end of detail calculations. 


= =RPG Il returns default value ‘N’ in the TERMINATION-INDICATOR of the PIB. If no 
error occurs (HO-H9 indicators set off), no abnormal termination indicator ‘S’ is set 
and no succession is indicated (the E, I, or D indicators set). 


The PIB is defined on the file description specifications form, and the PIB fields that are 
accessed or updated in the action program are described on either the input format 
specifications form, the output format specifications form, or both. There are two allowable 
specifications for the PIB on the file specifications form, columns 15 and 16: 


= Input, demand file (1 in column 15 and D in column 16) 


= Update, demand file (U in column 15 and D in column 16) 
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The input demand file specification indicates that the action program requires data from 
the PIB but does not want to change the data. The action program accesses the PIB any 
number of times during detail calculations via the READ operation. 


_ The update demand file specification indicates that the action program requires data from 
the PIB and wants to update the data. In this case, the action program accesses the PIB 
the same as an input demand file; however, it updates the PIB by issuing either the EXCPT 
operation in the calculations specifications or by using detail or total output specifications 
and letting the RPG Il logic perform the output. 


Only PIB fields referenced by an action program are defined on the input or output 
specifications forms. Any name can be specified for a PIB field referenced in your action 
program; however, the formats and positions of the fields referenced in the action program 
must agree with their definition and position in the IMS 90 PIB. (See Table 3-1 for the 
entries required to define the PIB on the file description specifications form.) 


3.3.1.3. Output Message Area (OMA) 


The OMA consists of a 16-byte control header plus the output message built by the action 
program and sent to a terminal in response to an input message. Use of the OMA in RPG 
Il action programs is optional; however, when the OMA is used, the OUTSIZE parameter of 
the IMS 90 ACTION configuration section must indicate the size of the user’s output 
message. 


The OMA can be used for multiple output messages during one action program execution. 
Also, an output message can be transmitted to a terminal other than the initiating terminal 
(e.g., message switching). To perform either of these operations, disk queueing must be 
configured for ICAM via the DISCFILE macro, and unsolicited outpout must be configured 
via the UNSOL parameter. 


lf an error occurs on a CALL ‘SEND’ to unsolicited output, the *ERROR field in the dump 
will contain a letter ‘K’ and at action program termination, ‘RPGO36’ will be displayed on 
the system console. 


When an output message is to be transmitted to a terminal other than the initiating 
terminal, output specifications for the switched message must appear before those for the 
required action termination message. Figure 3-7 illustrates the file description input 
format and output format specifications for a message switching operation. 
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Figure 3—7. Message Switching Program Specifications (Part 2 of 2) 
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3.3.1.4. Continuity Data Area (CDA) 


The CDA is used for passing data from one action program to its successor during a dialog 
transaction. Its size varies and its use is optional (3.6.5). If the CDA is used, its size is 
specified by the CDASIZE parameter of the IMS 90 configuration ACTION section. 


The CDA file is described as an input, update, or output file on the file description 
specifications form (column 15), and the fields within the file are described on the input 
format specifications form or the output format specifications form according to their use 
in the action program. Table 3-1 lists the required file description specification entries for 
the CDA. | 


An RPG Il action program can create, read, or update the CDA. If the action program is 
creating the CDA, it must define the CDA on the file specifications form as an output file. 
If it reads the CDA without changing any of its data, the action program must define the 
CDA as an input file on the file specifications form. When updating the CDA area and 
passing its data to the successor program, the action program must define the CDA as an 
update file on the file specifications form. When CDA is to be deleted, the action program 
moves zeros to the CONTINUITY-DATA-OUTPUT-LENGTH field in the PIB. Table 3-2 lists 
these actions. | 


Table 3—2. File Type Specifications for Creating, Moving, and Updating the CDA 


File Type Specification O ; 
eration 


| (input) Reads the CDA 
U (update) Reads and updates CDA contents and passes to successor program 
O (output) Creates the CDA 


3.3.2. User Logical Files and IMS 90 Defined Files 






RPG Il action programs access user logical ISAM, MIRAM, SAM, and DAM files as well as 
IMS 90 defined files. (To access IRAM files, you must define them as MIRAM files at 
configuration time.) User logical files are data files you create via OS/3 data management. 
Defined files are files created by IMS 90 from user logical files according to user-supplied 
data definitions. (See Section 2.) 


To be used by RPG Il action programs, user logical files that are not accessed by defined 
files must be identified by the FILES parameter of the configuration ACTION section. The 
FILE section of the configuration defines all logical files. Table 3-3 summarizes the file 
organization, related access methods, and file types used in an RPG II action program. 


In RPG Il action programs, ISAM files and defined files are specified and processed in the 
same manner. Table 3-4 lists the allowable file description specifications for logical and 
defined files. | 
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Table 3—3. Summary of File Organizations, Access Methods, and File Types Used by RPG II! Action Programs © 


File Related ee 
Organization Access Method Re A 2a 


IMS 90 Files: 















Input/Update/Output* 
input/Update/Output* 


Random 
Sequential 





Defined 










User Files: 












input/Update/Output* 
Input/Update/Output* 


Random 
Sequential, by key 





ISAM 




















IRAM or Indexed Random Input/Update/ Output* 
MIRAM Nonindexed Random Input/Update/ Output 
Sequential Input 






SAM 





*For output files, only ADD is allowed. 







DAM 


Table 3—4. Allowable RPG I! File Description Specifications for ISAM, |lRAM, MIRAM, DAM, and Defined Files 


File Name (Column 7—14) User-defined name 








File Type (Column 15) |, U, or O 


Aor P 

R 

blank 

| 

D 

blank 

Key Field Start Position 0001-9999 (1) 
(Column 35—38) 


Device (Column 40—46) | Must be disk device 
File Addition (Column 66) Blank or A 


NOTES: 









Record Address Type (Column 31) 












File Organization (Column 32) 







G@) ISAM, IRAM, MIRAM and defined files 
@) _—DAM files 


@)__ Sequential processing 
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© RPG Il action programs can process tape or disk SAM output files. Table 3-5 lists the RPG II file 
description specifications allowed for SAM output files. 


Table 3—5. Allowable RPG I! File Description Specifications for SAM Output Files 


File Name (Column 7—14) User-defined name 


File Type (Column 15) 


Record Length (Column 24—27) 
Overflow Indicator (Column 33—34) 
Line Counter (Column 39) 
Device (Column 40—46) 


All user files used by RPG Il action programs must be defined in file description 
specifications and input/output specifications. Record descriptions of IMS 90 defined files 
used by RPG Il action programs must match their descriptions in the IMS 90 configuration. 








An RPG Il action program can access ISAM, DAM, MIRAM, and IMS 90 defined files in 
random mode by defining them as chained files on the file description specifications 
(column 16). 


Under IMS 90, the RPG I! program retrieves one record at a time. Updating or deletion of 
the retrieved record must be done before the next record is retrieved. Records being added 
to or deleted from a file on which updating is being performed cannot be added or deleted 
between the reading and writing of a record that is being updated. The ADD or DEL 
specifications in columns 16-18 of the output format specifications perform add or delete 
functions. | 


3.3.3. Specifications Forms for RPG Iti Action Programs 


3.3.3.1. Control Card Specifications Form 


The RPG II control specifications form identifies the action program and specifies that the 
program is to be compiled as an IMS 90 action program. Column 74 requires the letter ‘A’ 
and columns 75-80 require a 1- to 6-character program name beginning with an 
alphabetic character. Table 3-6 lists the entries allowable on the control card 
specifications form. (For restrictions on control card specifications, see Table 3-7.) 
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Table 3—6. RPG I! Control Card Specifications for RPG I! Action Programs © 


Alternating Collating Sequence 
(Column 26} Blank or S 


ners Handling (Column 40) Blank, $, 1, O, or B 











Forms | Forms Alignment (Column 41) (Cotumn 41) Must be blank@ 
Indicator Initialization 
(Column 42) Blank or S 






File Translation (Column 43) | Blankor Fo | Blankor Fo F 


IMS 90 Action Program Indicator 

(Column 74) Must be A 

Program Identification 

(Column 75—80) Blank or program name 


NOTES: 





(1) ‘The file access method (MIRAM, ISAM, DAM) used in the 
program is not affected by this entry. This is determined by 
the IMS 90 configurator. 


(2) This field is an RPG I! option that is not permitted in an RPG II 
action program. 


3.3.3.2. File Description Specifications Form 


The file description specifications form describes the user logical files, defined files, and IMS 
90/RPG Ii interface areas used or referenced by an RPG Ii action program. Tables 3-4 and 
3-5 list the allowable file description specifications for user logical and defined files. Table 
3-1 shows the specifications required to define IMS 90/RPG II interface areas as files in the 
action program. (For restrictions on file description specifications, see Table 3-7.) 


3.3.3.3. Input Format Specifications Form 


The input format specifications describe the fields within user files, defined files, or IMS 
90/RPG Il interface areas referenced by the action program. The same rules apply for 
coding action program input format specifications as for normal RPG II programs. (For 
restrictions on input format specifications, see Table 3-7.) 
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Table 3—7. Restricted RPG Ii Language Features 


ee 


Control card specifications 





Error analysis dump 
Operator control 
First page forms alignment 





File description specifications File type (C and D) 
Table and array file designation (T) (1) 


Block length (2) 
File organization: 


ADDROUT (D) (1) 

Record address (blank) Cd) 
Additional! |/O areas Q) 

SAM tape/disk input files (1) 
ISAM and MIRAM output files 


Device: 


CTLRDR 
READER 
CRP 
PUNCH 
CONSOLE 
PRINTER 


Labels (2) 


Name of label exit option 8 





Size of ISAM index entry 

Unordered load 

Cylinder overflow space percentage (2) 
Number of extents (2) 

Tape rewind 

File conditioners (U1—U8) 


Extension specifications (1) Chaining (C1—C9) tables or arrays 


a 
Calculation specifications 28-32 Display operation (DSPLY) 


NOTES: 












Spread card feature (TR) | 
Stacker select 


Input format specifications 


(1) Used only with MIRAM files; must not be used with SAM input files. 


2) ignored by RPG II compiler; must be specified in IMS 90 configuration. 
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3.3.3.4. Calculation Specifications Form 
Operations on the files described on the file description specifications form and input or 


output format specifications forms can be specified on a calculation specifications. See 
Table 3-7 for restrictions on the use of calculation specifications. 


3.3.3.5. Qutput Format Specifications Form 

The output format specifications describe the complete output message on the file 
description specifications form. This output description includes DICE codes (see Appendix 
E) for screen display positioning, display headings, and data fields required by the action 
program. (See Figure C-8.) Output specifications also describe IMS 9O/RPG ll interface 
area fields referenced by the action program for use in external succession; e.g., PIB or 
CDA fields. For restrictions on the output format specifications, see Table 3-7. 

3.3.4. RPG Il Action Program Restrictions 

A number of the RPG II language features are restricted from use in an action program. 


Table 3-7 lists these features and their restrictions by column number and RPG Il 
specification form. 


3.4. BAL ACTION PROGRAMS 


3.4.1. Linkage Conventions 
An action program is treated as a subprogram of the IMS 90 online program and is 
activated by action scheduling using standard linkage conventions. When control is 
transferred to the action program entry point, the register contents are as follows: 
2 Register 1 points to a parameter list containing (in order): 

~ Program information block address 

— Input message area address 

- Work area address (optional) 

- Output message area address (optional) 


- Continuity data area address (optional) 


lf any of these parameters is not specified, the omission is indicated by a binary O in 
the parameter list. The position of parameters in the list is fixed. 
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= Register 13 contains the address of a 72-byte save area. The standard linkage 
conventions must be observed in the use of the save area. In particular, forward and 
backward save area links must be established to relate the save area given by register 
13. to the save area used by the action program to make Puen to IMS 90. for all 
functions. 


w Register 15 contains the address of the action program entry point. 


The action program must allocate space for a 72-byte, word-aligned save area to be used 
on calls to IMS 90 for all functions. This area must be properly linked to the save area 
provided by action scheduling for an action program. In all parameter lists that are passed 
to IMS 90, the sign bit must be set in the final parameter word. Standard linkage 
conventions must be observed. 


When a continuity data area is referenced in a BAL action program, the program should 
not save addresses of items within the area from one action to another. Since the location 
of the continuity data area for a transaction can change from action to action, any saved 
addresses can thereby be invalidated. 


3.4.2. Function Requests 


An action program must not contain any direct requests to OS/3 data management. All 
file |1/OQ functions must be requested through function calls in the form of CALL or 
ZG#CALL macros. (The difference between CALL and ZG#CALL is explained in 3.4.3.) 
Explicit message output, termination, and other functions also are requested in this 
manner. The format for CALL and ZGACALL is: 


[name] (CALL a ae ae 
ZG#CALL 


File |1/O and explicit message output functions are described in 3.8 and 3.9. Termination is 
requested via the RETURN function in this format: 


ZG#CALL ‘RETURN’ 


Execution of the RETURN function returns control to action scheduling. 


3.4.3. Reentrant Programming Considerations 
The following rules must be observed in coding a reentrant BAL action program: 


1. Instructions must not be modified during the execution of the action program. For 
example, the length field of an MVC instruction must not be stored into the 
instruction itself. The EX instruction can be used to modify the length field or the 
MVC instruction can be built and executed in the activation record. 
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2. Data must not be embedded in the action program. All references to variable data 
must be made to the activation record (i.e., the program information block, tnput 
message area, work area, output message area, and continuity data area). DSECTs 
can be used to conveniently reference the areas in the activation record. Constant 
data can be defined in the action program. 


3. Parameter lists containing addresses that vary from request to request or containing 
addresses of parameters defined in the activation record must be built in the 
activation record. The CALL macro with the (param-1,....param-n) form of the 
parameter list can be used only to make requests for which ali parameters are 
defined in the action program because the CALL macro generates a list of address 
constants in line for the parameter list. | 


The macro ZG#CALL can be used to make requests for which some or all of the parameters 
are defined in the activation record. ZG#CALL builds a parameter list at the user-defined 
location PLIST. PLIST must be at least a 16-byte area beginning on a word boundary within 
the activation record, typically within the work area. The parameter list is built by 
ZG#CALL through use of a series of LAand ST instruction pairs. The ZG#CALL macro must 
be used for the RETURN function; CALL RETURN is not valid in an action program. 


The following examples illustrate the difference in the use of the CALL and ZG#CALL 
macros: 


m CALL ESETL, (INFILE) 

=  INFILE is a constant defined in the action program. 
es ZG#CALL RETURN 

= No parameter list is generated. 

® ZG#CALL GET, (INFILE, RECORD, KEY) 


= INFILE is a constant defined in the action program, but RECORD and KEY are 
defined in the work area of the activation record. 


3.5. USER-WRITTEN RESIDENT SUBPROGRAMS 


BAL and COBOL action programs can call user-written resident subprograms. Thus, 
common functions, such as repetitive computations, need be coded only once, as 
subroutines, and then called by those action programs that need them. The fact that these 
subroutines are made resident guarantees their efficient use by not requiring that they be 
loaded into main storage each time they are called. They are loaded with IMS 90 during 
the start-up procedure. 
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User-written subprograms can be prepared as either serially reusable or reentrant load 
modules and must be resident in main storage to be called by a COBOL or BAL action 
program. They cannot be used with RPG II action programs and are not available in a basic 
IMS 90 system. 


A subprogram cannot call on another subprogram; however, a subprogram can issue all 
the function calls supported for action programs. Information is passed to the subprogram 
from the calling action program via a parameter list. A subprogram can access only those 
files that are allocated to the calling action program. 


Subprogram use must be specified in the IMS 90 configuration via the SUBPROG 
parameter in the OPTIONS section. In addition, the subprogram name must be specified on 
the program-name parameter of the PROGRAM section and SUBPROG=YES must be 
specified in the same section. The COBOL or BAL program must then place the 
subprogram name in the SUCCESSOR-ID field of the PIB before calling the resident 
subprogram. 


In case of error in a subprogram, IMS 90 provides snapshot dumps of both the calling 
action program and the active subprogram. 


3.5.1. Subprogram Reusability 


A resident subprogram can be serially reusable or reentrant; it cannot be shared. A serially 
reusable subprogram can read and write into its own area, the calling action program, and 
the activation record. If the originating action program is reentrant, the subprogram cannot 
modify the calling program. Reentrant subprograms are executed as read-only and can 
modify only the activation record. They can modify other areas of the calling action 
program only if it is nonreentrant. 


3.5.2. COBOL Action Program Interface 


A COBOL action program calls a resident subprogram with the following sequence: 


MOVE subprogram-name TO SUCCESSOR-ID. 

ENTER LINKAGE. 

CALL ‘SUBPROG’ [USING data-name-1...data-name-n]. 
ENTER COBOL. 


where: 


data-name-l...data-name-n 
Refer to data items in the data division of the COBOL action program. No more 
than 12 data-names can be specified. 


A subprogram written in COBOL returns control to the calling action program as follows: 


ENTER LINKAGE 
CALL ‘RETURN’. 
ENTER COBOL. 
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3.5.3. BAL Action Program Interface 


A BAL action program or subprogram calls a resident subprogram via me following 
macroinstruction: 


ee oe ,(param-1,..., param-n) 
ZG#CALL 
where: 

param-1l,..., param-n 


Refer to labels of storage locations in the BAL action program. Up to 12 
parameters can be specified. 


The calling action program must place the name of the called subprogram in the PIB at 
location ZA#PSID before issuing the ZG#CALL macro. The subprogram name must be left- 
justified and zero filled (X‘FO’) in a 6-byte area. 


When control is transferred to the called subprogram, register 1 points to the specified 
parameter list. Other register contents are as follows: 


# Register 13 points to a /2-byte save area supplied by the calling action program. The 
subprogram is responsible for saving the caller's registers, using standard save area 
linkages. If the subprogram requires working storage, the address of the working 
storage can be passed to the subprogram either in the parameter list or in a register. 


= Register 14 contains the return address. A subprogram returns control to the calling 
program via the ZG#CALL RETURN macro. 


= § Register 15 contains the entry point address of the subprogram. 
= Registers 2 through 12 have the same contents as the calling program. 


= Register O is unpredictable. 


3.6. ACTIVATION RECORD 

The activation record is made available to the user action program after the program is 
loaded and given control by IMS 90. The activation record consists of the following areas. 
lf present in a single-thread IMS 90 system, they appear in storage in the order listed: 
5 Program information block (PIB) 

@ Output message area (OMA) 


= Input message area (IMA) 


= #$Work area (WA) 
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# Continuity data area (CDA) 


a Defined record area (DRA) 


In the activation record layout for multithread IMS 90, the CDA and WA precede the IMA. 
(See Figures 3-16 and 3-1/7.) 


Formats for PIB, OMA, and IMA headers are available to the COBOL user in the IMS 90 
copy library under the names PIB, OMA, and IMA. For American National Standard 1974 
COBOL users, these names are PIB74, OMA74, and IMA74. The BAL user accesses these 
formats by calling DSECTs as macros from the $YSMAC system macro library or a user 
macro library. 


The ZM#DPIB macro calls the ZA#DPIB DSECT, the ZM#DOMH macro calls the ZAHOMH 
DSECT, and the ZM#DIMH macro calls the ZA#IMH DSECT. 


3.6.1. Program Information Block (PIB) 


The program information block is always present in. the activation record and is 136 bytes 
in length. It is used to communicate processing information between IMS 90 functions and 
the action program. The COBOL and BAL formats for the PIB are shown in Figures 3-8 
and 3-9. The COBOL description of the PIB is stored in the IMS 90 copy library under the 
name PIB or under the name PIB74 for American National Standard 1974 COBOL. The 
ZM#DPIB macro generates the PIB DSECT for a BAL program. The shaded area in Figure 
3-9 represents locations used only by IMS 90; a user-written BAL action program should 
never access these. 


The COBOL format PIB fields listed in Figure 3-8 are described in 3.6.1.1 through 3.6.1.6. 
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01 PROGRAM-INFORMATION-BLOCK 


02 STATUS-CODE PIC =©9(4) COMP-4. S 
02 DETAILED-STATUS-CODE PIC ©9(4) COMP-4. ( 
62  RECORD-TYPE REDEFINES DETAILED-STATUS-CODE. 
63 PREDICTED-RECORD-TYPE PIC X. 
63 DELIVERED-RECORD-TYPE PIC X. 
82  SUCCESSOR-ID | PIC X(6). @ 
62 TERMINATION-INDICATOR PIC X. 
82 LOCK-ROLLBACK-INDICATOR | PIC. X. 8 
62  TRANSACTION-ID. 
63 YEAR | | PIC 9(4) COMP -4. 
03 ODAY PIC 9(4) ComP-4. (@) 
63 TIME PiC §=©9(9) CoMP-4. G6) 
92 DATA-DEF-REC-NAME PIC = X(7). 8 
62 ODEFINED-FILE-NAME PiC = X(7). 
62 STANDARD-MSG-LINE-LENGTH 7 PIC §=©9(4) COMP-4. @ 
62  STANDARD-MSG-NUMBER-LINES PIC =©9(4) COMP-4. 
02 WORK-AREA-LENGTH PIC §=©.9(4) comPp-4. @ 
92 CONTINUITY-DATA-INPUT-LENGTH | PIC 9(4) COMP-4. (Q) 
92 CONTINUITY-DATA-OUTPUT-LENGTH PIC =. 9(4) COMP-4. @) 
$2 WORK-AREA- INC PIC 9(4) COMP-4. | 
692 CONTINUITY-DATA-AREA-INC PIC 9(4) COMP -4. 


92 SUCCESS-UNIT—ID. 
Q3 TRANSACTION-DATE. 


O04 YEAR PIC 99. 
64 MONTH PIC 99. 
64 DAY PIC 99. 
83 TIME-OF-DAY. 
94 HOUR PIC 99. 
94 MINUTE PIC 99. 
B4 SECOND PIC 99. 
Y 83 UNIQUE-SUFFIX PIC 999 
62  SOURCE-TERMINAL-CHARS. 
93 SOURCE-TERMINAL-TYPE PIC X. 
83 SOURCE-TERM-MSG-LINE-LENGTH PIC 9(4) COMP -4. 
93 SOURCE-TERM-MSG-NUMBER-LINES PEC 9(4) COMP -4. 
t NOTES: 
1) These fields are set by action scheduling at action initiation. All other PIB fields are set to O at initiation. 
@ These fields determine the termination procedures and may be Set by the action program prior to termination mode 
multithread. 
8) These fields aiso are used to return status information for 1/O requests issued by the action program. 
(4) The name for this field in American National Standard 1974 COBOL is TODAY. 
(5) The name for this field in American National Standard 1974 COBOL is HR-MIN-SEC. 


Figure 3-—-8. COBOL and American National Standard 1974 COBOL Format for Program Information Block 
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ZA#DPIB 
ZA#PSC 
ZA#PDSC 
ZA#PSID 
ZA#PSIND 
ZA#PSNN 
ZA#PSNA 
ZA#PSNS 
ZA#PSNI 
ZA#PSND 
ZA#PSNE 
ZA#PLRI 
ZA#PLRIN 
ZA#PLRIO 
ZA#PLRIH 
ZA#PLRIR 
ZA#PTID 
ZA#PDDRN 
ZA#PDFN 
ZA#PMLL 
ZA#PMNL 
ZA#PWA 
ZA#PCDIN 
ZA#PCDL 
ZA#PCDO 
LA#PWAI 
ZA#PCDI 
ZA#DTE 
ZA#TME 
ZA#UNID 
ZA#TTTYP 
ZAHTFCC 
ZA#TNON 
ZA#TWS 
ZA#TNOV 
ZA#TMLL 


DSECT PROGRAM- INFORMATION-BLOCK 


DS H 
DS H 
DS CLE 
DS Cll 
EQUATES FOR ZA#PSIND 
EQU CN’ 
EQU C‘A’ 
EQU C'S’ 
FEQU CI 
EQU  C‘D’ 
EQU CE’ 
DS Cll 
EQUATES FOR ZA#PLRI 
EQU = C‘N’ 
EQU C‘0’ 
EQU CH’ 
EQU = C'R’ 
DS CL8 
DS CL7 
DS CL7 
DS H 
DS H 
DS H 
DS H 
EQU* 
DS H 
DS H 
DS H 
DS CLE 
DS CLE 
DS CL3 
DS CLI 
EQUATES FOR ZA#TTTYP 
EQU C‘F’ 
EQU CV’ 
EQU = C‘W’ 
EQU sC'N’ 
H 


SS 
sererae 
LOCneeR SS 





STATUS-CODE 
DETAILED-STATUS-CODE 
SUCCESSOR-ID 
TERMINATION-INDICATOR 


NORMAL TERM 

ABNORMAL TERM 

ABNORMAL TERM WITH SNAP 
IMMEDIATE INTERNAL SUCCESSION 
DELAYED INTERNAL SUCCESSION 
EXTERNAL SUCCESSION 
LOCK-ROLLBACK-INDICATOR 


WRITE ROLLBACK POINT,RELEASE LOCKS 
ROLLBACK UPDATES 

HOLDS LOCKS IND 

RELEASE PENDING LOCKS IND 
TRANSACTION-ID 

DATA-DEF-REC-NAME 
DEFINED-FILE-NAME | : 
STANDARD-MSG-LINE-LENGTH 
STANDARD-MSG-NUMBER-LINES 
WORK-AREA-LENGTH 
CONTINUITY-DATA-INPUT-LENGTH 

CDA LEN : OS/3 BASIC 
CONTINUITY-DATA-OUTPUT-LENGTH 
WORK-AREA-INC 
CONTINUITY-DATA-AREA-INC 

CURRENT DATE — YYMMDD 

SUCCESS-UNIT TIME — HHMMSS 
SUCCESS-UNIT-UNIQUE-ID 

TERMINAL TYPE 


FULL FIELD CONTROL CHARACTER DEVICE 
VIDEO DEVICE WITHOUT FCC 
WORKSTATION 
NON-VIDEO DEVICE 
TERMINAL-MSG-LINE-LENGTH 

Al -MSG 


NODE tetas 
Sa 


RR 
SOSOHES 
SaaS 4 


= 
Deets 
ee 2 
NT 
beens 


areas 





Figure 3—9. BAL Format for PIB (ZAH#DPIB DSECT) 


Y 
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3.6.1.1. STATUS-CODE 


STATUS-CODE is a half-word binary integer value returned by IMS 90 that indicates the 
completion status of a request. The status code values that can be returned are: 


Description . Value 





Successful 0 
Invalid key or record number 

End of file or unallocated optional file 2 
Invalid request 3 
I/O error 4 
Violation of data definition 5 
Internal message control error 6 
Screen formatting error 7 


In general, an invalid request status code is returned when an error is detected in a 
request by IMS 90 before the request is passed to OS/3 data management, control 
system, or ICAM. An I/O error status code is returned when an unrecoverable error is 
detected by data management, the control system, or ICAM. 


An error return option can be specified for each action program at configuration time. If 
the option to accept errors is chosen (ERET=YES specified to the configurator), then, 
regardless of the value of the status code, control is returned to the action program after a 
function is completed. In this case, the action program must include tests for all status 
codes that are possible at the completion of the requested function. If the option to reject 
errors is chosen (or defaulted), then control is returned to the action program only if the 
Status code equals 1 or 2. If any other status code is returned, control is not returned to 
the action program. 
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3.6.1.2. DETAILED-STATUS-CODE 


DETAILED-STATUS-CODE is a half-word binary value returned by IMS 90 following a 
request when the status code !s either an invalid request, |/O error, or internal message 
control error. The detailed status code supplements the status code by providing more 
detailed information concerning the error. When the status code is I/O error, the detailed 
status code contains either filenameC+2 or the error code and subcode returned by the 
access method. All file types except MIRAM files return a detailed status code of 
filenameC+2. MIRAM files return an error code (DM) and subcode. When the status code 
is invalid request (3) or internal message control error (6), the detailed status code is a 
binary integer. The possible values for the detailed status code for invalid request (status 
code 3) are listed in Table 3-8. Detailed status codes are interpreted differently for internal 
message control errors on explicit output message processing. (See 3.9.2.) 


Table 3—8. Detailed Status Codes for Invalid Requests (Part 7 of 2) 


es 


Incorrect number of parameters The number of parameter addresses contained 
in a request parameter list is inconsistent with 
the function requested. This error can result 
from the failure of BAL action programs to set 
the sign bit in the final address word in a request 
parameter list as required by standard linkage 
conventions. 





Function code out of legal range This error may occur when the IMS 90 link 
| module that is linked to a serially reusable or 
sharable action program is inadvertently 
written into by the action program or control 
is improperly passed from an action program 
to IMS 90. 


Incorrect parameter value The parameter list address passed to IMS 90 
on a request is O, or an address contained in 
the parameter list is O, or the actual value of 
a parameter is incorrect. This error can also 
occur when an 1/O area for a DAMR 
file was not half-word aligned. 


Shared record not in use by this This code does not apply to user action 
transaction. program requests. 


File not defined A logical or defined file named in a request 
to IMS 90 has not been defined at configuration 
time or by means of the data definition 
processor. 


File not open A logical file named in a request to IMS 90 
has been closed from the master terminal (ZZCLS) 
or a logical file has been closed by data 
management as the result of an unrecoverable error. 


Function invalid for type of file The function specified in a request to IMS 90 is 
not valid for the type of file named. For example, 
a SETL for a nonindexed file. 
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Table 3—8. Detailed Status Codes for Invalid Requests (Part 2 of 2) 


1 084, Record(s) not locked. An UNLOCK request has been made when no 
> locks exist. 


re ~ PUT or DELETE function not preceded The function sequence for an update operation 
by a GETUP function is not valid. 


| TOR: "Mega function requested The requested function is not consistent with 
the DTF or RIB parameters in the configuration. 


A logical or defined file named in a request to 
IMS 90 has not been named in the configured 
definition of the action making the request, or 
a defined file has not been dynamically named 
by the preceding action. 






OB,. File not Assigned to this action 



















A request has been made that requires a 
module not included in the IMS 90 load 
module at configuration time. 


Required module not included in 
configuration. 






A request has been made to insert a record into 
a MIRAM or ISAM file, but insufficient space 
exists to contain the new record. 


Insufficient space in main storage User must allocate more main storage. 


Update not permitted in configuration 


Capacity exceeded on INSERT function 









A request has been made to perform some update 
function, but update has been disallowed at 
configuration time. 













Update suppressed for files The requested update is not permitted 
because of an I/O error in AUDFILE, a file 


used by online recovery. 







File recovery is not operational; only file displays 
are allowed. 


Trace file down 

















Record has been locked by another 
transaction (for single-thread only) 


Under single-thread, action program issued 
either a GETUP or INSERT function on a 

record, but this record was already locked by 
some other transaction. 







The DETAILED-STATUS-CODE field has special uses under defined record management, 
described in 3.8.6.1. In the COBOL description of the PIB, DETAILED-STATUS-CODE is 
redefined as RECORD-TYPE for this purpose and the two record type bytes under the 
redefined STATUS- BORE are PREDICTED-RECORD-TYPE and DELIVERED- RECORD TYPE. 


os PREDICTED-RECORD-TYPE is the one-byte alphanumeric indicator that specifies to 
the defined record management the type record expected from a GET, GETUP, or 
INSERT function call. It can also specify the type of the next sequential record 
expected as a result of the SETL and GET function calls. 


m DELIVERED-RECORD-TYPE is the one-byte alphanumeric indicator that specifies the 
type record actually returned by defined record management to the action program. 
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S$ 3.6.1.3. SUCCESSOR-ID 


SUCCESSOR-ID is the identification of the action program activated after the termination 
of the current action program. When either external or delayed internal succession is 
invoked, SUCCESSOR-ID must contain the name of the successor action. The required 
value must be moved to this field by the current action program if a successor is desired. 
This is a 6-byte field and the identification must be left-justified and zero filled (i.e., X‘FO’). 
No value need be specified on normal transaction termination. When the action program 
voluntarily chooses to terminate the transaction abnormally, a termination code is first 
moved to SUCCESSOR-ID. This termination code is useful in determining the cause of 
failure. If a code is specified, it is reported to the originating terminal operator (or console 
operator) after the abnormal termination occurs. 


3.6.1.4. TERMINATION-INDICATOR 


TERMINATION-INDICATOR is a 1-byte value, set by the current action program, that 
indicates the type of termination to take place for the program. The indicator has one of 
the following possible values: | 


N 


Indicates normal transaction termination. When the current action program 
terminates, messages are output and all resources including the current action 
program are released. This is the default value for the indicator. 





Indicates abnormal transaction termination. When the current action program 
terminates, IMS 90 creates and sends an error message to the originating 
terminal. All resources are released and files are rolled back, where applicable. 


Indicates abnormal transaction termination with snap dump. This option is the 
same as the A option except that, in addition, a snap dump of the action program 
and its activation record is performed. 


Indicates external succession. When the current action program terminates, 
messages are output, all resources including the current action program are 
released, and the succeeding action is scheduled when the next input message 
is received from the originating terminal. 
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Indicates immediate internal succession. When the current action program 
terminates, no message is output, the current action program is released, the 
succeeding action program is initiated, and all areas that were referenced by the 
terminating action program are passed to Its successor. Note that indiscriminate 
use of | in a multithread environment can cause deadlock. Avoid terminating with 
an | when the GETUP and SETL functions are outstanding in the current action. 


Indicates delayed internal succession. When the current action program 
terminates, no message is output, the output message is queued as input to the 
succeeding action, all resources (including the current action program) are 
released, and the succeeding action is initiated through normal scheduling 
procedures. 


When you use delayed internal succession, be sure to allocate adequate space 
for the input staging buffer via the INBUFSIZ parameter in the configurator 
GENERAL section. If insufficient buffer space is available for the successor 
program, the transaction terminates with a status code of 6 (internal message 
control error) and a detailed status code of 8 (record not locked). 


A summary of the types of termination by an action program is included in Table 3-9. 


Table 3—9. Summary of Action Program Termination Types 


Type of Termination 


: Action Action 
Action 


branrawednkormation Normal Abnormal Abnormal Transaction Eos Termination Termination 
aes Transaction Transaction Termination With Snap ti ve With Immediate With Delayed 

Block Data Items ae aan With External 

Termination Termination Dump internal internal 


Successor 
Successor Successor 


SUCCESSOR-ID Ignored Termination- Termination code Action Action Action 
—>- code program name program name program name 

TERMINATION- A S E 

INDICATOR 
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The TERMINATION-INDICATOR is used to control voluntary action program termination; 
i.e., termination that occurs after the execution of the CALL ‘RETURN’ statement. An 
action program also can terminate involuntarily. Involuntary termination occurs when an 
abnormal condition is encountered by IMS 90 in the processing of a request issued by an 
action program. (See description of STATUS-CODE, 3.6.1.1). Involuntary termination also 
can occur when the execution of an action program Causes a program check or when an 
execution loop within an action program continues beyond a specified time limit. When 
either of these conditions occurs, the standard abnormal termination message is sent to 
the originating user terminal and to the system console. In addition, a snap dump of the 
action program and its activation record is performed. (Refer to 3.12 for a description of 
the snap dump.) 
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@ 3.6.1.5. LOCK-ROLLBACK-INDICATOR 


LOCK-ROLLBACK-INDICATOR is a 1-byte value, set by the action program, that indicates 
to action scheduling the record lock and rollback functions that are to be performed at 
action termination. The indicator is set to one of the following values: 


H 
Causes all record locks that have been imposed in the action to be held into the 
subsequent action. | 

N 
Establishes a new rollback point in the audit file for this transaction and releases 
all locks for this transaction. This is the default value. 

O 
Causes the rollback of all updates performed by this transaction to the previous 
rollback point, releases all locks for this transaction, and establishes a new 
rollback point in the audit file for this transaction. 

R 

& Causes the release of all locks for pending updates that have been imposed in 


the action. A record lock is pending if GETUP is done for it but no PUT function is 
issued for the record. 


R and H options are effective only when the termination indicator is set to E (external) or D 
(delayed internal). In long transactions, R and H options should be used with caution. 
Holding of locks across many actions in a multithread environment can cause deadlocks. 


The N option is useful for long-running update transactions. The N option releases all 
locks when the termination indicator is set to E (external) or D (delayed internal). It also is 
used to establish additional rollback points, to limit the range of rollback, and to cut down 
the size of the audit file. By limiting the number of updates in an action or by establishing 
additional rollback points in a long-running transaction, you can reduce the size of the 
audit file and thus save disk space. 


The O option is effective for N (normal), as well as E and D, and causes online file 
recovery to be activated to carry out the rollback. In the case of N (normal transaction 
termination), a new rollback point is established in the audit file. 
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3.6.1.6. Additional PIB Fields & 
The remaining COBOL format fields of the PIB contain the following information: 


# $TRANSACTION-ID is the date-time stamp for the first input message of a transaction. 
It is set by action scheduling for the use of all action programs that are activated 
during the processing of a transaction. The date is given in Julian form. The time is in 
milliseconds. The TRANSACTION-DATE and TIME-OF-DAY under SUCCESS-UNIT-ID 
should be used by the action program when accurate date and time of day are 
required. | 


= DATA-DEF-REC-NAME is the name of the data definition record (in the named record 
file) that contains the description of the defined file designated by DEFINED-FILE- 
NAME. This is a 7-byte item and the name must be left-justified and blank filled. 


When an action is scheduled, IMS 90 moves the record name specified by the 
DDRECORD parameter in the configurator ACTION section into this field and the file 

name specified by the DFILE parameter into the DEFINED-FILE-NAME field, unless 

values were left in these fields by the preceding action. If the action terminates in 

delayed internal or external succession and the successor action accesses a different 

defined file, the action program can either move the record name and file name for 

the successor action into these fields or can zero out both fields and let IMS 90 insert 

the values specified to the configurator for the successor action. If the successor 

action accesses only logical files, zeros also should be placed in both PIB fields. This 
allows the successor action to access logical records that have contributed to the & 
defined file used by the previous action. 


= DEFINED-FILE-NAME is the name of a defined file that is to be accessed. DEFINED- 
FILE-NAME is a 7-byte item and the name must be left-justified and blank filled. Its 
use is described under DATA-DEF-REC-NAME. 


# STANDARD-MSG-LINE-LENGTH is a half-word binary integer set by action scheduling 
that specifies the configuration-defined maximum line length for a message. 


# STANDARD-MSG-NUMBER-LINES is a_ half-word binary integer set by action 
scheduling that specifies the configuration-defined maximum number of lines for a 
message. | 


= WORK-AREA-LENGTH is a half-word binary integer set by action scheduling that 
specifies the length of the work area allocated to the action. 


ms CONTINUITY-DATA-INPUT-LENGTH is a _ half-word binary integer set by action 
scheduling that specifies the length of the continuity data record that was passed to 
this action by its predecessor. The continuity data record, if present, begins with the 
first byte of the continuity data area. 


a CONTINUITY-DATA-OUTPUT-LENGTH is a half-word binary integer set by action 
scheduling that specifies the length of the continuity data area allocated to the action. “a 
This value determines the number of bytes in the continuity data area, starting with @ 
the first byte, that are to be saved when termination with external succession or 
delayed internal succession is requested. The value is changed in the current action 
prior to termination to reduce the size of the continuity data record that is saved. 
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=» WORK-AREA-INC is a half-word binary integer set in the current action program. This 
value specifies the number of bytes in addition to the value specified in the action 
control table at configuration time that should be allocated for the successor of the 
current action. This is implemented in multithread only. 


e CONTINUITY-DATA-AREA-INC is a half-word binary integer set in the current action 
and is used to increment the length of the continuity data area. This increment value 
is added to the length of the saved continuity data record and compared to the length 
specified in the action control table to determine the larger, which becomes the size 
of the continuity data area for the succeeding action. 


m SUCCESS-UNIT-ID provides a data and time stamp to the user program at the 
beginning of each success unit. A success-unit is defined as an action. 


= SOURCE-TERMINAL-TYPE is a 1-byte field that contains a type code for the source 
terminal. The values set by IMS 90 are: 


Value Description 

C'F’ Full field control character (FCC) device (i.e., UTS 400) 
CV’ Video device without FCC (i.e., U100, U200) 

CW" Workstation 

C'N’ Nonvideo device (i.e., teletypewriter, batch terminal) 


= SOURCE-TERM-MSG-LINE-LENGTH is a half-word binary integer that specifies the 
number of characters per line for the source terminal. For a nonvideo device, however, this 
value is the configured line length (CHRS/LIN specification in the GENERAL section of the 
IMS 90 configuration). 


=» SOURCE-TERM-MSG-NUMBER-LINES Its a half-word binary integer that specifies the 
number of lines for the source terminal. For a nonvideo device, however, this value is 
the configured number of lines (LNS/MSG specification in the GENERAL section of 
the IMS 90 configuration). 


3.6.2. Output Message Area (OMA) 


The output message area is optional and has a length as specified by the OUTSIZE 
keyword parameter in the configurator ACTION section. The output message area is 
divided into a control header and an area for the message text. The message text portion 
is set to blanks at initiation. If an output message area is selected for an action and the 
action terminates normally, the message in the area is sent to the originating terminal 
unless otherwise specified. Figures 3-10 and 3-11 show the predefined COBOL and BAL 
formats for the OMA contro! header. The COBOL description of the OMA control header is 
available in the copy library under the name OMA or under the name OMA/74 for 
American National Standard 1974 COBOL. Execution of the macro ZM#DOMH in a BAL 
~ action program generates the OMA DSECT. 
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DESTINATION-TERMINAL-ID is the identifier of the terminal to which the output message 
is to be sent. If no value is moved to this item prior to the termination of the action, the 
source terminal is assumed to be the destination terminal. The identifier must be left- 
justified and blank filled. The four bytes (FILLER) following this field are reserved for 
system use. 


SFS-OPTIONS is used to specify information about the screen format that is being used. If 
the first byte of the field is set to the character I, this format is to be used for the following 
input. Any other value in this field means this format is not to be used for the following 
input. 


CONTINUOUS-OUTPUT-CODE is used to identify a continuous output message, when 
continuous output is being generated. The continuous output option is described in 3.10. 


TEXT-LENGTH is a binary half-word integer that specifies the length of the output 
message text. The value specified in TEXT-LENGTH must include the length of the actual 
text plus four bytes for the length field. This value is set to the predefined output message 
text length by action scheduling at action initiation and is reduced by the action program. 
The output message text length is specified in the configuration definition of an action. If 
the value is set to zero and no explicit output message has been sent by the action 
program, a default termination message is sent to the source terminal. 


AUXILIARY-DEVICE-ID is used to specify whether the output message is to be sent to an 
auxiliary device and, if so, to identify the device. This field also can be used to specify 
additional printing options. If the output message is not to be sent to an auxiliary device, 
set the entire field to binary O's; this is the original value of the field, set by IMS 90 when 
it generates the OMA header. For example, in a COBOL action program 


MOVE LOW-VALUES TO AUXILIARY-DEVICE-ID. 


States that the output message is not to be sent to an auxiliary device, but is to be 
displayed or listed on the primary device - the destination terminal with no special options. 


On the other hand, if the output message is to be listed on an auxiliary device attached to 
the destination terminal, you must use each byte of the AUXILIARY-DEVICE-ID field. 





UP-8614 Rev. 1 SPERRY UNIVAC OS/3 3-43 


IMS 90 APPLICATIONS 


a a a 





QUTPUT-MESSAGE-AREA. 
DESTINATION-TERMINAL-ID PIC X(4). 
SFS-OPTIONS PIC X(2). 
FILLER PIC X(2). 
CONTINUOUS-OUTPUT-CODE PIC X(4). 


TEXT-LENGTH PIC 9(4) COMP-4. 
AUXILIARY-DEVICE-ID. 
83 AUX-FUNCTION 

93 AUX-DEVICE-NO 


PIC X. 
PIC X. 





Figure 3—10. COBOL and American National Standard 1974 COBOL Format for OMA Control Header 


ZA#0OMH 


* 


DSECT 


OUTPUT MESSAGE HEADER 
ZA#ODTID DS CL4 
ZA#OSFSO DS CL2 


DESTINATION TERMINAL 1D 
SFS OPTIONS 


* EQUATES FOR ZA#OSFSO 


* 





ZA#OSFSI 


ZA#CONT 
ZA#OMHL 
ZA#OTL 

ZA#OAUX 


EQU 


DS 
DS 
EQU 
DS 
DS 


a 


CL2 

XL4 
“—ZA#0MH 
H 

CL2 


. EQUATES FOR ZA#0AUX 


* 


ZA#ONCOP 
ZA#0CO 
ZA#001Q 


LA#OHANG 


ZA#OCOP 

ZA#OCOCP 
ZA#OPTCP 
ZA#OPCOC 


Figure 3—11. 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


X' 86° 
X‘ C3" 
X' C9" 
X‘' DO’ 
‘Eg! 
(63) 
(EA? 
OFT? 


INPUT FORMAT 


RESERVED FOR SYSTEM USE 
CONTINUOUS OUTPUT CODE 
OUTPUT MSG AREA HEADER LENGTH 


MESSAGE LENGTH 


AUXILIARY-DEVICE-1ID 


NO COP SUPPORT REQUESTED 


CONTINUOUS OUTPUT 


REQ 


QUEUE AS INPUT FOR DEST: TCT 
RESERVED FOR IMS/96 SYSTEM USE 
COP OUTPUT REQUESTED 


CONTINUOUS OUTPUT 
PRINT TRANSPARENT 
CONTINUOUS OUTPUT 
PRINT TRANSPARENT 


TO COP 
TO COP 
TO COP WITH 





BAL Format for OMA Control Header (ZAHOMH DSECT) (Part 1 of 2) 
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; $$: SPACE SUPPRESSION Iss: INHIBIT SPACE SUPPRESSION @ 
' C: CONTINUOUS OUTPUT NC: NOT CONTINUOUS OUTPUT 
ZA#O0CSPM EQU X‘'F3' 3: €,SS,PRINT MODE 
ZAHONSPM EQU X‘' FQ’ @: NC,SS,PRINT MODE 
ZA#OCSPT EQU X‘'F7' 7: €,SS,PRINT TRANSPARENT 
ZA#ONSPT EQU X‘F4’ 4: NC,SS,PRINT TRANSPARENT 
ZA#OCIPM EQU X'F5' 5: C,1SS,PRINT MODE 
ZA#ONIPM EQU X‘F2' 2: NC,ESS,PRINT MODE 
ZA#OCIPT EQU X' FQ’ 9: C,ISS,PRINT TRANSPARENT 
ZA#ONIPT EQU X'F6' 6: NC,1SS,PRINT TRANSPARENT 
ZA#OCSPF EQU X'C1’ A: C,SS,PRINT FORM (ESC H) 
ZA#HONSPF EQU X'D1' J: NC,SS,PRINT FORM (ESC H) 
ZA#OCSTA EQU X‘'C2’ B: C,SS,TRANSFER ALL (ESC G) 
ZAHONSTA EQU X‘D2’ K: NC,SS,TRANSFER ALL (ESC G). 
ZA#OCSTV EQU X‘C4' D: C,SS,TRANSFER VARIABLE (ESC F) 
ZA#ONSTV EQU X‘'D4’ M: NC,SS,TRANSFER VARIABLE (ESC F) 
ZA#OCSTC EQU eee E: C,SS,TRANSFER CHANGED (ESC E) 
ZA#ONSTC EQU X‘'D5' N: NC,SS,TRANSFER CHANGED (ESC E) 
ZAHOCIPF EQU X‘C6' F: C,1SS,PRINT FORM (ESC H) 
ZAHONIPF EQU X‘'D6' 0: NC,ISS,PRINT FORM (ESC H) 
ZA#OCITA EQU X‘'C7' G: C,ISS,TRANSFER ALL (ESC G) 
ZA#ONITA EQU X‘'D7' P: NC,ISS,TRANSFER ALL (ESC G) 
ZA#OCITV EQU X‘'C8' H: C,1SS,TRANSFER VARIABLE (ESC F) 
ZA#ONITV EQU X‘'D8' Q: NC,ISS,TRANSFER VARIABLE (ESC F) 
ZA#OCTIC EQU X'E8’ Y: C,1SS,TRANSFER CHANGED (ESC E) 
y ZA#ONITC EQU X‘'F8" 8: NC,ISS,TRANSFER CHANGED (ESC E) 
ZA#ONTRM EQU x‘D9 R: C,READ MODE 
ZA#ONTRT EQU X‘E2’ S$: C,READ TRANSPARENT 
ZA#HONTSR EQU X‘E3’ T: C,SEARCH AND READ MODE 
ZAHONTST EQU X‘E5' V: C,SEARCH AND READ TRANSPARENT 
ZA#ONTRA EQU X‘E6' W: C,REPORT ADDRESS 
A ZAHOCTBB EQU X‘'D3’ L: C,BACK ONE BLOCK 
ZA#ONTBB EQU X‘E7" X: NC,BACK ONE BLOCK 
ZA#OCTSP EQU X‘ EQ’ Z: C,SEARCH AND POSITION 
X‘'E4' U: NC,SEARCH AND POSITION 


ZA#ONTSP EQU 


. EQUATES FOR ZA#0AUX+1 
ZA#ODID1 EQU 
ZA#ODID2 EQU 
ZA#ODID3 EQU 
ZA#ODID4 EQU 
ZA#ODIDS EQU 
ZA#O0DID6 EQU 
ZA#ODID7 EQU 
ZA#ODID8 EQU 
ZA#ODID9 EQU 


DEVICE = AUX1 
DEVICE = AUX2 
DEVICE = AUX3 
DEVICE = AUX4 
DEVICE = AUX5 
DEVICE = AUX6 
DEVICE = AUX? 
DEVICE = AUX8 
DEVICE = AUX9 


Omar OrI DOM OO O&O 
oc, © cn & & BO = 


Figure 3—117. BAL Format for OMA Control Header (ZA#OMH DSECT} (Part 2 of 2) 
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To list the output message on the COP or TP in print mode, for example, set the AUX- 
FUNCTION byte of this field to X‘FO’; to list it in print-transparent mode, set the AUX- 
FUNCTION byte to X’F4’. You must also set, in the AUX-DEVICE-NO byte of the same field, 
a character in the range 1-9 (that is, X‘F1’ through X‘F9’) to identify the auxiliary device. 
This number corresponds to the logical device number appended to the AUX keyword 
parameter of the TERM declarative macro in your ICAM network definition. (See the IMS 
90 system support functions user guide/programmer reference, UP-8364 (current 
version).) For example, in a COBOL action program, the statements 


MOVE ‘4°’ TO AUX-FUNCTION. 
MOVE ‘1° TO AUX-DEVICE. 


cause the output message to be sent to an auxiliary device at the primary destination 
terminal and listed in print-transparent mode; the device specified is the first auxiliary 
device configured at that terminal. Print mode, print-transparent mode, space suppression, 
and other print options are further described in 3.10.1.1 (in the context of printing 
continuous output). Table 3-16 summarizes the settings of the AUX-FUNCTION byte. 


3.6.3. Input Message Area (IMA) 


The input message area is required for all actions. Its size is specified at configuration 
with the INSIZE keyword parameter in the ACTION section. When no length is specified for 
the input message area at configuration time or the length specified is inadequate, an area 
large enough to contain the actual input message is allocated by action scheduling. This 
area contains the input message when the first and subsequent action programs of an 
action are activated. If the input entered from the terminal is a function key (5.1.5), IMS 90 
creates a message in the format: 


F#nn 


This message is preceded by the DICE sequence: 


10819161 


This DICE sequence is present even if you specified DICE=OFF in your ICAM network 
definition. However, if you have configured input message editing (any specification except 
NO on the EDIT parameter in the ACTION section), the DICE sequence is stripped from the 
message before it is sent to your program. 


The area also contains information related to the message in a control header. When the 
input message area is larger than the actual input message plus the control header, the 
balance of the area is blank filled. The COBOL and BAL formats for the IMA control header 
are shown in Figures 3-12 and 3-13. The COBOL description of the IMA header is 
available in the copy library under the name IMA or under the name IMA/74 for American 
National Standard 1974 COBOL. Execution of the ZM#DIMH macro in a BAL action 
program generates the DSECT for the IMA header. 
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INPUT -MESSAGE-AREA. 
02 SOURCE-TERMINAL-1ID PIC X(4). 
62 DATE-TIME—STAMP. 
03 YEAR PIC 9(4) COMP-4, 
63 DAY PIC 9(4) COMP-4. Q) 
93 TIME PIC 9(9) COMP-4. (@) 
TEXT-LENGTH PIC 9(4) COMP-4. 
AUXILIARY-DEVICE-ID. 
63 FILLER PIC X. 
63 AUX-DEVICE-NO PIC X. 


NOTES: 
(1) ‘The name of this field in American National Standard 1974 COBOL is TODAY. 


@) The name of this field in American National Standard 1974 COBOL is HR-MIN-SEC. 





Figure 3—12. COBOL and American National Standard 1974 COBOL Format for IMA Control Header 


ZA#1MH DSECT 


* [INPUT MESSAGE HEADER 

ZA#ISTID DS CL4 SOURCE TERMINAL 1D 

ZA#IDTS ODS CL8 DATE/TIME STAMP 

ZA#IMHL EQU *“—ZA#IMH INPUT MESSAGE AREA HEADER LENGTH 
ZA#ITL DS H TEXT LENGTH 

ZA#IDEV DS Ci2 AUXILEARY-DEVICE-ID 


EQUATES FOR ZA#IDEV+1 

DEVICE=AUX 
DEVICE=AUX 
DEVICE=AUX 
DEVICE=AUX 
DEVICE=AUX 
DEViCE=AUX 
DEVICE=AUX 
DEViCE=AUX 
DEVICE=AUX 


ZA#IDIDI EQU 
ZA#IDID2 EQU 
ZA#IDID3 EQU 
ZA#IDID4 EQU 
ZA#IDIDS EQU 
ZA#IDID6 EQU 
ZA#IDID7 EQU 
ZA#IDIDS EQU 
ZA#IDID9 EQU 


om Om 7 3 oO! oO OO US} 
wocwns &D wm SS GW MH = 
wcwins & cn &@ Ww AS = 





Figure 3—13. BAL Format for IMA Control Header (ZARIMH DSECT} 
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The IMA control header contains the following items: 


= SOURCE-TERMINAL-ID is the identifier of the terminal that originated the input 
message. 


= DATE-TIME-STAMP is the value of the date and time at which the input message was 
made available to internal message control. The date-time is provided in binary. The 
first half word of the field contains the year; the second half word contains the Julian 
day. The second word contains a sequence number unique to this input message and 
not usable for determining the time of day. 


= TEXT-LENGTH is a binary half-word integer that specifies the length of the input 
message text. The two bytes (FILLER) following the TEXT-LENGTH field are reserved 
for system use. The value specified in TEXT-LENGTH includes the length 2 the actual 
text plus four bytes for the length field. 


# AUXILIARY-DEVICE-ID is the number of the auxiliary device from which data is 
transmitted to the action program. 


3.6.4. Work Area (WA) 


The work area is optional for most programs; however, it is generally used by sharable or 
reentrant action programs requesting file |/O functions. The. work area is used as 
modifiable working storage for the input and output of defined records and logical data 
records via IMS 90 file management. The work area also is used for the building of output 
messages that are explicitly sent via internal message control. The length of the area is 
equal to the length specified in the action control table at configuration time plus the 
length specified as WORK-AREA-INC in the PIB by the preceding action. WORK-AREA-INC 
is not Supported in single-thread IMS 90. If the WORKSIZE parameter is not specified in 
the configurator ACTION section, no work area is generated. The work area, if generated, 
is set to binary O's at initiation. 


3.6.5. Continuity Data Area (CDA) 


The continuity data area is optional. It is used to contain data that is passed from action to 
action in a dialog transaction. 


If a fixed-length continuity data area is required in a dialog transaction, the length of the 
area is specified in the action control table record for the first action by means of the 
CDASIZE parameter in the configurator ACTION section. The record is then passed from 
action to action by action scheduling without further intervention by the action programs. 


It is possible to vary the length of the continuity data area from action to action or to 
eliminate the area when the succession is made from one action to another. These 
changes are accomplished by varying the parameters that determine CDA length. 
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The length of the area is equal to the larger of: 


= the length specified in the action control table at configuration time for the action 
being scheduled; or 


= the length specified as CONTINUITY-DATA-INC in the PIB by the preceding action plus 
the actual length of the continuity data record saved at the termination of the 
preceding action. | 


The actual length of the record saved is specified in CONTINUITY-DATA-OUTPUT-LENGTH 
in the PIB of the preceding action. The same value is made available to the succeeding 
action in the CONTINUITY-DATA-INPUT-LENGTH entry of the PIB. Either the CONTINUITY- 
DATA-INC specified by the preceding action or the continuity data area length specified in 
the action control table, or both, is zero. If the value in CONTINUITY-DATA-OUTPUT- 
LENGTH is zero when an action terminates, then no record is saved for the succeeding 
action in the continuity data file. 


The continuity data area is set to binary O's at action initiation. The continuity data record, 
if any, is then read into the area as its starting location. 


3.6.6. Defined Record Area (DRA) 


The defined record area is used by defined record management. A DRA is generated if the 
DDRECORD parameter is specified in the ACTION section of the configuration for this user 
action or if DEFINED-FILE-NAME in the PIB contained a defined file name when the action 
that named the current action as its successor terminated. The DRA is approximately 400 
bytes long plus four times the maximum logical record size plus two times the record key 
size. 


The defined record area is not specified in the action program and cannot be written into 
by the action program. 


3.7. LINK EDITING ACTION PROGRAMS 


After you obtain a clean action program compilation, you must link it to the IMS 90 link 
module, ZF#LINK, in one job using the LINK jproc in the following format: 


// LINK action-prog-name, a 
(RES, $Y$LOD) 


{ This LINK jproc can be used only when the action program is compiled with the PARAM 
OUT=(M) statement or the 7/7 PARAM IMSCOB=YES statement. This procedure produces 
a load module and places it in the IMS 90 load library for later reference. This library must 
be the same one specified on the LIBL parameter of the IMSCONF jproc at configuration. 
(The default value for the LIBL parameter is $Y$LOD.) 


If an action program is not compiled with either of the shared code PARAM statements, an 
4 ENTER statement naming the program to be linked must be included in the tink stream. 
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ZF#LINK has a defined entry point for each of the IMS 90 functions that an action program 
can request. During execution, when an action program calls an IMS 90 function, control 
passes to ZF#LINK. ZFA#LINK, in turn, passes control to IMS 90, which executes the 
function. After completion of the requested service, control returns from the IMS 90 
module directly to the action program at the return point designated in the function call. 





3.8. FILE PROCESSING 

IMS 90 file management makes records available to action programs for processing. In 
turn, user-written action programs issue file |/O functions to retrieve, insert, update, or 
delete records. IMS 90 file management supports sequential, relative, and indexed files. In 
addition, it supports defined files in an indexed file organization via defined ‘record 
management. 

An IMS 90 action program can issue one or more I/O function calls: GETUP, GET, PUT, 
DELETE, INSERT, SETL, and ESETL. These calls are processed by SAM, DAM, ISAM, or Y 
MIRAM access methods. (To access IRAM files, you must define them as MIRAM files at 
configuration time.) Table 3-10 summarizes the files supported by IMS 90. 


Table 3—10. Summary of Files Supported by IMS 90 File Management 


Access Data Management Functions Available 
Mode Access Method Through IMS 90 
File Management 
Sequential Sequential SAM/dedicated MIRAM| Retrieve, Append 
(tape and disk) i(write unblocked output) 
Relative Random DAM/MIRAM Retrieve”, Update, 
(nonindexed) — insert, Delete 


Indexed Random ISAM/MIRAM Retrieve*, Update 
Insert, Deiete 


Random ISAM/DAM/ Retrieve*, Update, | 
MIRAM Insert, Delete 

Sequential ISAM/DAM/ Retrieve | 
MIRAM 


* Both retrieve and retrieve-with-the-intent-to-update can be requested. 


















File 
Organization 


















Indexed 
(Defined File) 





UP-8614 Rev. 1 SPERRY UNIVAC OS/3 3-50 


IMS 90 APPLICATIONS — Update A 





Y 


f 


An action program may issue random or sequential |/O functions to indexed and relative 
files but only sequential |/O functions to sequential files. Table 3-11 lists the file I/O 
functions allowed with each file organization. 


Table 3—11. Summary of File 1/O Function CALL Statements 


Sequential GET USING file-name record-area. 
. PUT USING file-name record-area. 


Relative GET USING file-name record-area record-number. SETL USING file-name position 
(nonindexed) GETUP USING file-name record-area record-number. } [record-number]. 

PUT USING file-name record-area [record-number]. GET USING file-name: record-area. 
INSERT USING file-name record-area record-number. | ESETL USING file-name. 
DELETE USING file-name record-area record-number. 












































GET USING file-name record-area key. 
GETUP USING file-name record-area key. 
PUT USING file-name record-area. 
INSERT USING file-name record-area. 
DELETE USING file-name record-area. 


SETL USING file-name positon 
[key{partial-key-count]]. 

GET USING file-name record-area. 
ESETL USING file-name. 


Indexed 

















GET USING file-name record-area key. 
GETUP USING file-name record-area key. 
PUT USING file-name record-area. 
INSERT USING file-name record-area key. 
DELETE USING file-name record-area. 


Indexed 
(Defined File) 


SETL USING file-name position [key]. 
GET USING file-name record-area. 
ESETL USING file-name. 








NOTES: 


G) — Sequential functions available with MIRAM, not DAM 


(@) Required for DAM relative files 


3.8.1. Formats and Rules for File 1/O Functions 
The four following general rules apply to file I/O functions: 


1. In an action program coded in extended COBOL, function requests are preceded and 
followed by ENTER statements: 


ENTER LINKAGE. 
CALL ‘GET’ USING file-name record-area key. 
ENTER COBOL. 


Action programs coded in 1974 American National Standard COBOL do not use 
ENTER statements. 


2. Function requests made in BAL action programs use either the CALL or the ZG#CALL 
macro. (Refer to 3.4.2 for details.) An example of a BAL function request that is 
equivalent to the preceding COBOL function call is: 


CALL GET, (file-name,record-area,key) 
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®@ 3. The completion status of a function request is set in the program information block. 
Values for the status codes are listed in the description for each function. Values of 
detailed status codes are listed in Table 3-8. 


4. The positional parameters file-name, record-area, record-number, key, and position 
refer to data names in the data division of a COBOL action program or labels of 
storage locations in a BAL action program. The locations they represent contain the 
following values at the time the 1/O function is performed: 


=» File-name contains the 7-character name of the file on which the specified 
function is to be performed. This name must be left-justified and blank filled. 


= Record-area is the area to or from which a logical or defined record is to be 
moved by file management. The size of the record area must be equal to or 
greater than the size of the largest logical record it is to contain. In the case of a 
variable-length record, the record begins with the length field. COBOL 
programmers do not usually have to be aware of the length field, but they must 
include a description of this field in their description of a variable-length record 
when writing an action program. 


= Record-number is an 8-byte field containing a right-justified binary number 
identifying a record in the file. The number designates the position of the record 
relative to the beginning of the file. The first number is 1. 


@ 2 Key contains the key value used to identify a record to be retrieved from a file or 
inserted into a file. 


= Position contains a 1-byte value designating the position of the file at the 
completion of the SETL function. Values are listed in the description of the SETL 
function. 


3.8.2. Indexed Files 


The indexed sequential, indexed random, and multiple indexed random access methods 
(ISAM, IRAM, and MIRAM) process function calls issued by your action program to indexed 
files. With several exceptions, a key specification characterizes most file functions issued 
to indexed files. Although IMS 90 supports multiple key MIRAM files, you must use only 
the key identified in the configurator FILE section (KEYn parameter) to retrieve or update 
records. No duplicate keys are allowed on MIRAM files. Changes to alternate keys are 
allowed. 


3.8.2.1. Random Functions for Indexed Files 
The random function calls GET, GETUP, PUT, INSERT, and DELETE retrieve records with or 


without updating, write records back to a file, logically delete records, and overwrite an 
existing record or add a new record to a file. 
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3.8.2.1.1. GET and GETUP Functions 


The random GET function only retrieves the record. The GETUP function retrieves the 
record for updating and temporarily locks the requested record from access by other 
transactions. Random GET and GETUP functions are not performed if the requested record 
is currently locked by a different transaction. File keys supplied as parameters in a GET or 
GETUP function locate the required record in a logical file. Any key required for a function 
need only be as long as the key field itself. 


A GET function must not be followed by a PUT or DELETE function; however, a GETUP 
function can be followed by a PUT function to update the record or a DELETE function to 
mark the record as logically deleted. A value of X’FF’ in the first byte of data in the logical 
record indicates the logical deletion of that record. When a transaction requests a record 
with X‘FF’ in the first byte, an invalid key status code is returned. To be effective, PUT or 
DELETE functions must immediately follow the GETUP function. If other functions 
intervene, the record must be retrieved again with a GETUP function before a PUT or 
DELETE can be performed. The key field must remain unaltered until the PUT or DELETE 
function is completed for ISAM files or until after the GETUP function is completed for 
MIRAM files. No key parameter is given on the PUT or DELETE functions issued to indexed 
records because the key was already given in the preceding GETUP function. 


COBOL and BAL formats for the random GET and GETUP function calls and resulting 
status codes follow: 


COBOL Format: 


ia hr ale file-name record-area key. 


‘GETUP’ 
BAL Format: 
ee UqGET poner eae Ones ve ey 
ZGHCALLY{GETUP 


Status Codes: 


Successful 

Invalid key 

Unallocated optional file* 
Invalid request 

1/O error 


PWN — © 


“This code applies to MIRAM files only. 





UP-8614 Rev. 1 SPERRY UNIVAC OS/3 3-53 
IMS 90 APPLICATIONS 


3.8.2.1.2. PUT Function 

The random PUT function is used with the GETUP function to write an updated record 
back to the file. A PUT function must be preceded by a GETUP function that retrieves the 
requested record for update. The first byte of nonkeyed data in a record must not be an 
X'FF’. Keys are not supplied on PUT functions issued to indexed files. 

COBOL and BAL formats for the PUT function call and resulting status codes follow: 
COBOL Format: 


CALL ‘PUT’ USING fite-name record-area. 


BAL Format: 


ee Pa een eres eee 
ZG#CALL 


Status Codes: 


Successful 

Not used 

Unallocated optional file* 
Invalid request 

I/O error 


ARWNH-—O 


3.8.2.1.3. INSERT Function 


The INSERT function places a new record into the file or overwrites a previously deleted 
record. This function is not preceded by a GETUP function. The first byte of nonkey data in 
the record being inserted must not contain a deleted record value of X’FF’. Any INSERT 
function using a previously deleted record slot not only removes the delete control 
character but also changes the record length field for variable-length records. Changing 
the length of a variable-length record is permitted for MIRAM files only. It is not allowed 
for ISAM files. Indexed files do not require a key parameter in the INSERT function. Their 
keys must be embedded in the record. The key of the new record must have a value that is 
different from any that already exist in the file. No additional 3 bytes of work space are 
required following the embedded key. 


COBOL and BAL formats for the random GET and GETUP function calls and resulting 
status codes follow: 


COBOL Format: 


CALL ‘INSERT’ USING file-name record-area: 


*This code applies to MIRAM files only. 
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BAL Format: © 


ere pecs oalganren nemerdine awe nen) 
ZG#CALL 


Status Codes: 


~ Successful 
Not used 
Unallocated optional file* 
Invalid request 
I/O error 


PWN — © 


3.8.2.1.4. DELETE Function 


The DELETE function logically deletes a record that was retrieved for updating. This 
function must be immediately preceded by a GETUP function for a record to be deleted. If 
other functions intervene between the GETUP and DELETE functions, the GETUP function 
must be reissued before the record can be DELETED. The DELETE function changes the 
first byte of nonkey data in a record retrieved for update to X‘FF’ before the record is 
written to the file. The DELETE function is invalid if the first byte of nonkey data is part of 
an alternate key. 


COBOL and BAL formats for the DELETE function call and resulting status codes follow: eS 
COBOL Format: 


CALL. ‘DELETE’ .USING. file-name.record-area: 


BAL Format: 


i ane DELETE,(file-name,record-area) 
ecru | 


Status Codes: 


Successful 

Not used 

Unallocated optional file* 
Invalid request 

I/O error 


WH — © 


*This code applies to MIRAM files only. 
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©} 3.8.2.2. Sequential Functions for Indexed Files 


Sequential function calls SETL, GET, and ESETL set an indexed file into sequential mode 
and position it to a selected location in the file, retrieve records sequentially, and reset the 
indexed file from sequential mode to random mode. 


When you access an indexed file sequentially, your action program must first set the file 
into sequential mode via the SETL function. During this time, files are accessed exclusively 
by the transaction that set the mode. Requests by other transactions for sequential or 
random mode functions are queued for later processing. 


sequential mode exists until your program requests an ESETL function or until the current 
action terminates. In either case, the indexed file returns to random mode. 


NOTE: 
Shared file access among transactions is done only in the random mode. The use of 


sequential mode by one transaction can significantly degrade the response time for other 
_transactions accessing the same file. 


3.8.2.2.1. SETL Function 


The SETL function sets an indexed file into sequential mode and logically positions the file 
according to the following position values: 


Value Meaning 








Beginning of file 

Greater than or equal to the key supplied 
Equal to key supplied 

Greater than key supplied 


LAG 


The value of the position parameter determines the logical position of the file at 
completion of the SETL function. You can reissue the SETL function any time you wish to 
change the sequential position of the file. For ISAM files, however, you must issue an 
ESETL function before reissuing another SETL function. 


You must supply a file name and choose a position value on the SETL function for indexed 

files. Depending upon the position chosen, you may optionally supply a key parameter. In 
addition, the SETL function allows for partial key search of indexed MIRAM files. To do 

this, you supply the optional partia/ key count parameter. The partial key count parameter 

is the symbolic address of a one-word field containing a right-justified binary number. This i 
binary number indicates the number of key argument leading bytes used for the 
positioning search. Table 3-12 explains the SETL parameter choices for indexed files. 
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Table 3—12. SE&ETL Parameter Choices for Indexed Files 





¢ 


ee fs Parameters meters 
File Type 
ee ee rtial 
Key a 


eee ee 
ae eee eet 
rena [xf [x Pe Pe De De 










NOTES: 
1. The ietter X means applicable to this file type. 
2. Key and partial key count are not used with position value B. 


The COBOL and BAL formats for the SETL function call and resulting status codes follow: 
COBOL Format: 


CALL ‘SETL’ USING file-name position[key[partial-key-count]]. 


BAL Format: 


bbe CES AINE age wt arate agen arene tenn aan 
ZG#CALL 


Status Codes: 


O Successful 

1 Invalid key 

2 Not used 

3 Invalid request 
4 (I/O error 


3.8.2.2.2. GET Function 


The sequential GET function retrieves the next logical record in sequential order unless 
the record is marked logically deleted (i.e., X‘FF’ in the first byte). if the record is marked 
logically deleted, the GET function then retrieves the following record. File-name and 
record-area parameters are required on sequential GET functions for indexed files. The 
COBOL and BAL formats for the sequential GET function call and resulting status codes 
follow: 


COBOL Format: 


CALL ‘GET’ USING file-name record-area. 
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BAL Format: 


ee cera enennr yee ts ay 0) 
ZG#CALL 


Status Codes: 


Successful 

Not used 

End of file or unallocated optional file 
Invalid request — | 

{/O error 


WN — © 


3.8.2.2.3. ESETL Function 

The ESETL function changes the mode of indexed files from sequential back to random. If 
a file is in the sequential mode for a transaction and you do not issue an ESETL function 
before termination of the current action, IMS 90 file management resets the file to random 
mode. The ESETL function always requires a file-name parameter. The COBOL and BAL 
formats for the ESETL function call and resulting status codes follow: 

COBOL Format: 


CALL ‘ESETL’ USING file-name. 


BAL Format: 


ar pee nne vscwel 
ZG#CALL 


Status Codes: 


O | Successful 

1 and 2 Not used 

3 — Invalid request 
4 I/O error 


3.8.3. Relative Files 


The direct, indexed random, and multiple indexed random access methods (DAM, IRAM, 
and MIRAM) process function calls issued by your action program to relative files. A 
record-number parameter characterizes most file functions to relative files although record 
numbers are not always required on sequential functions to relative files. 
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3.8.3.1. Random Functions for Relative Files 


The random function calls GET, GETUP, PUT, INSERT, and DELETE retrieve records with or 
without updating, write records back to a file, logically delete records, and overwrite an 
existing record or add a new record to a file. 


A DAM file must be preformatted offline before its initial use and must contain the 
maximum number of physical records to be referenced online under file management. For 
processing IRAM files, all volumes in a file must be mounted online. 


3.8.3.1.1. GET and GETUP Functions 


The random GET function only retrieves the record. The GETUP function retrieves the 
record for updating and temporarily locks the requested record from access by other 
transactions. Random GET and GETUP functions are not performed if the requested record 
is currently locked by a different transaction. When issued to relative files, the GET and 
GETUP functions must supply a record number. File relative record numbers supplied as 
parameters in a GET or GETUP function locate the required record in a logical file. All 
record number fields must be eight bytes long. 


A GET function must not be followed by a PUT or DELETE function; however, a GETUP 
function can be followed by a PUT function to update the record, or a DELETE function to 
mark the record as logically deleted. A value of X‘FF’ in the first byte of data in the logical 
record indicates the logical deletion of that record. When a transaction requests a record 
with X‘FF’ in the first byte, an invalid record number status code is returned. 


COBOL and BAL formats for the random GET and GETUP function calls and resulting 
Status codes follow: 


COBOL Format: 


es ee ene file-name record-area record-number. 
“GETUP’ 


BAL Format: 


a tee ,(file-name,record-area,record-number) 
ZGHCALL) (GETUP 


Status Codes: 


Successful 

Invalid record number 
Unallocated optional file* 
Invalid request 

I/O error 


f&WNH— Oo 


"This code applies to MIRAM files only 
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3.8.3.1.2. PUT Function 


The random PUT function is used with the GETUP function to write an updated record 
back to the file. A PUT function must be preceded by a GETUP function that retrieves the 
requested record for update. The first byte of nonkeyed data in a record must not be an 
X'FF’. A record-number parameter is required on the PUT function for DAM files, but ts 
optional for other relative files. Nevertheless, if you omit record-number for MIRAM files, 
you must place the GETUP function immediately before the PUT function. 


COBOL and BAL formats for the PUT function call and resulting status codes follow: 
COBOL Format: 


CALL ‘PUT’ USING file-name record-area [record-number ]. 
BAL Format: 


CALL ents marge ee pe [,record-number ] ) 
ZG#CALL 


Status Codes: 


Successful 

Invalid record number 
Unallocated optional file* 
Invalid request 

I/O error 


PWN oO 


3.8.3.1.3. INSERT Function 


The INSERT function places a new record into the file or overwrites a previously deleted 
record. This function is not preceded by a GETUP function. The first byte of nonkey data in 
the record being inserted must not contain a deleted record value of X‘FF’. For MIRAM 
files only, any INSERT function using a previously deleted record slot not only removes the 
delete control character but also changes the record length field for variable-length 
records. 


INSERT functions issued to a relative file must supply a record-number parameter. If you 
specify RCB=NO at configuration, any record you add to a relative file must be assigned a 
relative record number one higher than the last record in the file. This prevents the 
occurrence of erroneous data between the last record and the new inserted record. You 
may insert records within or beyond the limits of nonindexed MIRAM files; file extension is 
permitted. 


COBOL Format: 


CALL ‘INSERT’ USING file-name record-area record-number. 


*This code applies to MIRAM files only. 
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BAL Format: 


ae feeb yee ance ne ee ma eee reer vagene er” 
ZG#CALL 


Status Codes: 


Successful 

Invalid record number 
Unallocated optional file* 
Invalid request 

|[/O error 


AhWN— OO 


3.8.3.1.4. DELETE Function 


The DELETE function logically deletes a record that was retrieved for updating. This 
function must be immediately preceded by a GETUP function for a record to be deleted. If 
other functions intervene between the GETUP and DELETE functions, the GETUP function 
must be reissued before the record can be DELETED. 


You must supply a record-number parameter on the DELETE function for DAM files; 
however, record-number parameters are optional on DELETE functions for other relative 
files. The DELETE function changes the first byte of nonkey data in a record retrieved for 
update to X‘FF’ before the record is written to the file. 


COBOL and BAL formats for the DELETE function call and resulting status codes follow: 
COBOL Format: 


CALL ‘DELETE’ USING file-name record-area [record-number]. 


BAL Format: 


CALL peepee nannies se {,record-number ] ) 
ZG#CALL 


Status Codes: 


Successful 

Invalid record number 
Unallocated optional file* 
Invalid request 

I/O error 


BmWNH— © 


*This code applies to MIRAM files only. 


f 
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© 3.8.3.2. Sequential Functions for Relative Files 


Sequential function calls SETL, GET, and ESETL set nonindexed IRAM and MIRAM relative 
files into sequential mode and position them to a selected location in the files, retrieve 
records sequentially, and reset these relative files from Sequential mode to random mode. 
Sequential functions cannot be processed by the direct access method (DAM). 


When you access an indexed file sequentially, your action program must first set the file 
into sequential mode via the SETL function. During this time, files are accessed exclusively 
by the transaction that set the mode. Requests by other transactions for sequential or 
random mode functions are queued for later processing. 


Sequential mode exists until your program requests an ESETL function or until the current 
action terminates. In either case, the indexed file returns to random mode. 


NOTE: 
Shared file access among transactions is done only in the random mode. The use of 


sequential mode by ane transaction can significantly degrade the response time for other 
transactions accessing the same file. 


3.8.3.2.1. SETL Function 


eS The SETL function sets a relative file into sequential mode and logically positions the file 
according to the following position values: 


Value Meaning 





Beginning of file 

Greater than or equal to the record number supplied 
Equal to record number supplied 

Greater than record number supplied 


IrAG WwW 


The value of the position parameter determines the logical position of the file at 
completion of the SETL function. You can reissue the SETL function any time you wish to 
change the sequential position of the file. 


You must supply a file name and choose a position value on the SETL function for relative 
files. Depending upon the position chosen, you may optionally supply a record-number 
parameter. Table 3-13 explains the SETL parameter choices for relative files. The SETL 
function is not available for DAM files. 
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Table 3—173. SETL Parameter Choices for Relative Files 


| 
File Type 
eae 
Number 













NOTES: 
1. The letter X means applicable to this file type. 
2. Record number is not used with position value B. 


The COBOL and BAL formats for the SETL function call and resulting status codes follow: 
COBOL Format: 


CALL ‘SETL' USING file-name position[record-number ]. 


BAL Format: 


eae peer ae ROARS gg esas camer Wome 
ZG4#CALL 


Status Codes: 


QO Successful 

1 Record number 
2 Not used 

3 = Invalid request 
4 1/0 error 


3.8.3.2.2. GET Function 
The sequential GET function retrieves the next logical record in sequential order unless 
the record is marked logically deleted (i.e., X‘FF’ in the first byte). If the record is marked 


logically deleted, the GET function then retrieves the following record. 


File-name and record-area parameters are required on sequential GET functions for 
relative files. The COBOL and BAL formats for the sequential GET function call and 
resulting status codes follow: 

COBOL Format: 


CALL ‘GET’ USING file-name record-area. 
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BAL Format: 


aa Po CORRE ec ans een 
ZG#CALL 


Status Codes: 


Successful 

Not used 

End of file or unallocated optional file 
Invalid request 

I/O error 


WHO 


3.8.3.2.3. ESETL Function 

The ESETL function changes the mode of relative files from sequential back to random. If a 
file is in the sequential mode for a transaction and you do not issue an ESETL function 
before termination of the current action, IMS 90 file management resets the file to random 
mode. The ESETL function always requires a file-name parameter. The COBOL and BAL 
formats for the ESETL function call and resulting status codes follow: 

COBOL Format: 


CALL ‘ESETL’ USING file-name. 


BAL Format: 


CALL nae 
ZGH#CALL 


Status Codes: 


0 Successful 

1 and 2 Not used 

3 Invalid request 
4 I/O error 


3.8.4. Sequential Files 


The sequential and dedicated multiple indexed random access methods (SAM and 
dedicated MIRAM) are the only access methods that can process function calls issued by 
your action program to sequential files. Only two functions, the sequential GET and PUT, 
can be issued to sequential files. The same SAM or dedicated sequential MIRAM file 
cannot be used for both input and output. (It is defined in the configurator FILE section as 
an input file or an output file.) Files used for input may only be accessed by the sequential 
GET function. For output files, only the sequential PUT function may be used. 
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3.8.4.1. Sequential Input GET Function @ 


The sequential GET function retrieves the next logical record in sequential order unless 
the record is marked logically deleted (i.e., X‘FF’ in the first byte). If the record is marked 
logically deleted, the GET function then retrieves the following record. The first record of a 
sequential file retrieved in an IMS 90 session is always the first record of the file. No 
record is ever read twice in a sequential file. 


File-name and record-area parameters are required on the GET function for sequential 
files. The COBOL and BAL formats for the sequential GET function call and resulting 
status codes follow: 


COBOL Format: 


CALL ‘GET’ USING file-name record-area. 


BAL Format: 


i ee ain eye ot 
ZG#CALL 


Status Codes: 


Successful 
Not used © 
End of file (DAM files only) or unallocated optional file (MIRAM files only) 

Invalid request 


1/O error 


h@NH— © 


3.8.4.2. Sequential Output PUT Function 
The sequential PUT function writes fixed- or variable-length logical records to sequential 
files on tape or disk. File-name and record-area parameters are always required on this 


function. Standard labeled tapes are assumed prepped or file space allocated for disk files 
before you issue a sequential PUT function. 


The COBOL and BAL formats for the sequential PUT function call and resulting status 
codes follow: 


COBOL Format: 


CALL ‘PUT’ USING file-name record-area. 
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@ : BAL Format: 


CALL a a a 
ZG#CALL 


Status Codes: 


Successful 

Not used 

Unallocated optional file* 
Invalid request 

|[/O error 


awh — Oo 


3.8.5. Defined Record Management 


Defined record management is the part of IMS 90 file management that services requests 
from action programs to retrieve and update the records of defined files. An action 
program can call upon the random access functions INSERT, GET, GETUP, PUT, and 
DELETE and also the sequential access functions SETL, GET, and ESETL. In response, IMS 
90 places defined records into and takes them from the record area you name in the I/O 
function call. 


A transaction can access only one defined file during a given action -— the file that was 
allocated before the beginning of the action. One action of a transaction can select a 
defined file that is not allocated to it and designate that the selected file be allocated to 
the succeeding action. (See the description of the DEFINED-FILE-NAME field in 3.6.1.6.) 





During a given action, a transaction can access only one defined file but can also access 
ISAM, SAM, DAM, IRAM, or MIRAM files if they are not referenced by the defined file. 
You must access standard files by using the I/O function calls pertaining to them. (See 
3.8.2, 3.8.3, and 3.8.4.). 


Certain rules apply to defined records and to the parameters accompanying the function 
calls for them. 


The following are parameter definitions for defined record management I/O function calls: 


x ## File-name is a data name (COBOL) or storage location (BAL) that contains the 7-byte 
defined file name or subfile name that has been assigned to this action. 


= Position is a data name or storage location containing the value B, G, or H, and 
determines which defined record is returned by the first execution of the GET call 
following the SETL function call. | 


B 


® : 


Retrieves the first record of the file. 


Retrieves the first record whose identifier (key) is equal to or greater than 
that specified by the key parameter. 


*This code applies to MIRAM files only. 
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Retrieves the first record whose identifier is greater than that specified by 
the key parameter. 


= Key is a data name or storage location that contains the identifier of a defined record. 
The identifier follows the rules specified in the data definition for the defined file fi/e- 
name. An identifier consists of one or more identifier segments. A segment must be 
delimited by an end-of-segment character (3D,,.), unless the segment contains the 
maximum number of characters defined for it, in which case this character is 
optional. Every segment must contain at least one character. The entire identifier 
must be delimited by an end-of-identifier character (3E,,¢). The ignore character (3F4.) 
can appear any number of times within the identifier and is always ignored. 


«  # Record-area is a data name or storage location that designates the area into which a 
defined record is moved by defined record management on an input function or from 
which a defined record is passed to defined record management on an output 
function call. This area must be big enough to contain the entire defined record, 


—_- including item status bytes. 


3.8.5.1. Defined Record Management Returns to Action Program 


In response to a function call, defined record management determines the type of defined 
record (as specified in the TYPE statement of the data definition) involved in the call and 
returns the record type to the action program in the program information block. 


PREDICTED-RECORD-TYPE | DELIVERED-RECORD-TYPE 


DETAILED-STATUS-CODE 
Redefined as RECORD-TYPE 


Before issuing any random GET, GETUP, or INSERT function request, the action program 
can indicate to defined record management the record type it expects to receive by placing 
it in the PREDICTED-RECORD-TYPE byte of the DETAILED-STATUS-CODE. If defined 
record management finds a value other than zero, it verifies the prediction before carrying 
out the retrieval or insertion. If the predicted type is not correct, the record involved is not 
moved; instead, a status code of 7 Is returned to the calling program. If the predicted type 
is correct, the function is carried out, and the PREDICTED-RECORD-TYPE byte reverts to 
zero. The action program, therefore, can use the PREDICTED-RECORD-TYPE byte prior to 
the request to prevent an unexpected type of defined record from being moved to or from 
the record area. If the defined file contains more than one type of defined record, the 
programmer is strongly advised to use this feature. This assures that further processing 
will apply the correct defined record definition. 
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When you issue the sequential function calls SETL and GET, defined record management 
returns the record type of the next sequential record to your action program in the PREDICTED- 
RECORD-TYPE byte. If the delivered record type is the parent of the predicted record type and 
you wish to access records from a record type other than currently indicated in the PREDICTED- 
RECORD-TYPE byte, you can change the contents of the predicted record byte in your action 
program to equal the DELIVERED-RECORD-TYPE byte. The result is that all sets subordinate to 
the current delivered record type are skipped. When one or more records in a set have already 
been delivered, you cannot change the PREDICTED-RECORD-TYPE byte to skip over the 
remaining records of that set. 


When defined record management responds to a GET, GETUP, PUT, or INSERT function 
request, it also places a value in the status byte associated with each item of the defined 
record. (Status bytes are allocated by the data definition processor and have data names in 
the format S-item-name. See Figures 2-38 and 2-39 for sample data definition processor 
output listings showing status bytes.) These values can be tested by the action 
programmer (in COBOL programs for fixed-length records but not variable-length records) 
to check the validity of individual items in the defined record. 


The value X‘80’ is returned by defined record management for all functions to indicate that 
the item has been successfully delivered. 


For GET and GETUP functions, defined record management returns a value of X’40’ to 
indicate that the item cannot be retrieved because it is null (nonexistent). Null items 
contain blanks if alphanumeric, zeros if numeric. If X’40’ is returned for one or more items 
along with a value of zero in the status code of the PIB, it generally means that a 
supplement cannot be found via the value in the pointer item. If returned along with a 
value of 1 in the status code, it generally means that the key parameter points to a 
nonexistent primary part. 


For PUT and INSERT functions, defined record management returns a value of X‘20' in the 
item status byte, along with a value of 5 in the status code of the PIB, to indicate that the 
item being changed or added does not conform to conditions specified in the data 
definition. This can be caused by any of the following: 

= the new item value does not meet VALUE statement conditions; 

= the new item value is inconsistent with the PICTURE clause in the data division; 

= a change was not permitted for this item (PUT only); or 


= no new value was entered for a MUST ADD item (INSERT only). 


lf an error occurs while accessing a file before returning control to the action program, 
defined record management changes the lock-rollback-indicator to “‘O”. 
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3.8.5.2. Random File |/O Functions & 
To access defined files randomly, you may issue the GET, GETUP, PUT, DELETE, and 


INSERT functions calls. During random access to defined files, logical record locks are 
imposed on logical records involved in the GETUP and INSERT functions. 


3.8.5.2.1. GET and GETUP Functions 

The GET and GETUP functions retrieve the record identified by the key parameter from the 
named file and place the record into the record area. A GET function cannot be followed 
by a PUT or DELETE function. The GETUP function retrieves a record for update and can 
be followed by a PUT or DELETE function. 

COBOL Format: 


es alae file-name record-area key. 


‘GETUP’ 
BAL Format: 
ee eet eA Uanas nen ae pe eeene 
ZGHCALLY)(GETUP 
Status Codes: é 
QO Successful 
1 Invalid key 
2 Not used 
3. ~=Invalid request 
4 I/O error 
5 Violation of data definition 


3.8.5.2.2. PUT Function 


The PUT function writes a record that was retrieved for update back to the file. The PUT 
function must immediately follow the GETUP function for the record to be updated. 


COBOL Format: 
CALL ‘PUT’ USING file-name record-area. 
BAL Format: 


re perpen et ane ee ee setae) 
ZGHCALL 
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© Status Codes: 
0 Successful 
1 and 2 Not used 
3 Invalid request 
4 I/O error 
5 Violation of data definition 


3.8.5.2.3. DELETE Function 


The DELETE function logically deletes a record that was retrieved for update. The DELETE 


function must immediately follow the GETUP function to effectively delete the record. ame 


COBOL Format: 
CALL ‘DELETE’ USING file-name record-area. 
BAL Format: 


be oe ee ae eee eva eee 
ZG#CALL 


Status Codes: 





0 Successful 

1 and 2 Not used 

3 _ Invalid request 

4 | I/O error 

5 Violation of data definition 


3.8.5.2.4. INSERT Function 


The INSERT function enters a new record into a file. The identifier value in the key 
parameter must not already exist in the file. 


COBOL Format: 
CALL ‘INSERT’ USING file-name record-area key. 
BAL Format: 


ae ic aaa 
ZG#CALL 
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Status Codes: 


O Successful 

1 Invalid key 

2 Not used 

3 = Invalid request 

4 1/0 error 

5 Violation of data definition 


3.8.5.3. Sequential File 1/O Functions 


To access defined files sequentially, you may issue the SETL, sequential GET, and ESETL 
function calls. 


3.8.5.3.1. SETL Function 
The SETL function sets a defined file into the sequential mode and logically positions the 


file. The position parameter is a data name or storage location that contains one of the 
following values: 


Value Meaning 

B Beginning of file 

G Greater than or equal to key 
H Greater than key 


COBOL Format: 


CALL ‘SETL’ USING file-name position [key]. 


BAL Format: 


pe pr ae eee epee [, key]) 
ZG#CALL 


Status Codes: 


Successful 
Invalid key 
Not used 
Invalid request 
[/O error 


hWNM— OO 
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NOTES: 
1. The key parameter is omitted when the value of position is B. 


2. Invalid key means that the identifier is not within defined bounds. That is, the 
defined record type cannot be determined from the value of the identifier. This 
code is not used to indicate missing data. The successful completion (status code 
of O) does not preclude the possibility that ensuing GET calls will yield only total 
cycles and no detail defined records. 


3.8.5.3.2. GET Function 


The GET function retrieves the next defined record in the file in sequential order. 


COBOL Format: 


CALL ‘GET’ USING file-name record-area. 


BAL Format: 


CALL ‘iia ial 
ZG#CALL 


Status Codes: 


O Detail cycle 

1 Invalid record type 
2 Total cycle 

3 = Invalid request 
4 1/0 error 

NOTES: 

7. If a status code is O (detail cycle), a new defined record is returned to your action 
program. The detailed status code identifies the record type. (See 3.8.4.7.) 

2. A status code of 2 means that there are no more records in the current set. No new 
defined record is returned. The detailed status code indicates the record type of the 
completed set. A status code of 2 with a detailed status code of O indicates end of all 
data; there are no more sets in this defined file. 

3. After a detail record is delivered, all subordinate records are also delivered in 
response to subsequent GETs. When a set of subordinate records is empty, the 
response to the GET function that requests the first record of the set is a status code 
of 2 and a detailed status code equal to the record type of the empty set. 

4. Your action program selects the appropriate record area by interrogating the value in 


the first byte of the DETAILED-STATUS-CODE (predicted record type) returned by the 
preceding GET or SETL function. 
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3.8.5.3.3. ESETL Function © 


The ESETL function changes the mode of a defined file from sequential to random. If a file 
is in the sequential mode and an ESETL function is not performed before termination, the 
file is changed to random mode at termination by IMS 90 file management. 

COBOL Format: 


CALL ‘ESETL’ USING file-name. 


BAL Format: 


CALL ee enenp een 
ZG#CALL 


Status Codes: 


O Successful 
1 and 2 Not used 
3 Invalid request 
4 |[/O error 
3.8.6. Online File Recovery ® 


The recovery facility provides for the rollback of user data file modifications (updates, 
{ inserts, and deletions) that have occurred in a transaction that abnormally terminates prior 
to completion or explicitly requests rollback prior to completion. When transactions 
terminate abnormally, IMS 90 issues messages to the source terminal and system 
console. These messages are documented in the OS/3 _ system messages 
programmer/operator reference, UP-8076 (current version). Each IRAM, MIRAM, ISAM, or 
4 DAM file modified in the transaction prior to the time of rollback is returned to the logical 
state that existed before the transaction was initiated or before the last rollback point was 
recorded on the audit file. Rollback occurs automatically when needed upon abnormal! 
termination and does not require any user programming. 


Rollback can be requested upon the normal termination of an action by specifying the O 
option of the LOCK-ROLLBACK-INDICATOR in the program information block. The range of 
rollback can be limited to less than an entire update transaction by specifying the N option 
of the LOCK-ROLLBACK-INDICATOR in the program information block upon the 
termination of some intermediate action in a dialog update transaction. 


an 
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The current state of each record that is to be updated or deleted is recorded in the IMS 90 
audit file prior to the update or deletion. In addition, the identifiers inserted into the file 
are recorded prior to insertion. Information also is recorded in the audit file to mark the 
initiation and termination of each transaction that modifies a file. When rollback points are 
specified, they are also recorded on the audit file. Online file recovery uses the audit file to 
accomplish file rollback. Table 3-14 lists the specific functions performed in the rollback of 
file modifications. 


Table 3—14. File Rollback 


: Functions Performed 
Functions that 


File Modification are to Roli Back 
Cause Modification eeiacy oe 
Modification 


Update GETUP, PUT GETUP (current image), 


PUT (before-image) 


Delete GETUP, DELETE INSERT (before-image) 
GETUP (current image) 
Insert IN , 
_ ena 


3.8.6.1. File 1/O Error Returns 





When unrecoverable !/O errors occur in the audit file, the source terminal operator is 
notified and a message is sent to the print file. Rollback is attempted for all existing 
transactions that have been logged in the audit file. IMS 90 prohibits any additional update 
requests (unless the LOCK=UP parameter is specified in the configurator FILE section) and 
returns an invalid request code (3) in the STATUS-CODE field of the PIB, as well as a 
binary value in the DETAILED-STATUS-CODE field. (Detailed status codes for file I/O 
functions are listed in Table 3-8.) 
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3.8.6.2. Prefix Area Format © 


If an 1/O error occurs on a user data file during the rollback of a file modification (updates, 
inserts, deletions), a snapshot dump is taken of the prefix area of the record being rolled 
back. Upon completion of the snapshot dump, the rollback procedure continues until 
rollbacks of all modifications made to user data files for a transaction are attempted. 


If an error occurs on the AUDCONF continuity data and audit file or the AUDFILE during 
the rollback of updates made by a transaction, the current action program name (contained 
in the prefix area of the record being rolled back) will be ZUAROL. 


The format of the prefix area is shown in Figure 3-14. Table 3-15 describes the content of 
each field. | 


0 1 2 


3 
7 rae transaction | 
8 terminal control table address 


12 


transaction id 
16 


20 


24 = tt), . 
initial action 

28 program name 

current action 


rogram name 
39 prog 


36 


date and time stamp 
at time of audit 


40 


44 key length reserved for system use 
48 data length of updated record 


52 filename 





Figure 3—14. Format of Prefix Area of Records in the Audit File (Online Recovery) 
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Table 3—15. Content of Prefix Area for Records in the Audit File {Online Recovery} 


ZFH#RTC Type code Binary Bits Set 
to 1 Meaning 
Not used 
Not used 
Termination 
Not used 
Rollback point 
Before-image, MIRAM 
aa, Before-image, ISAM 
Before-image, DAM 
ZFHAFB Flag byte Binary Bits Set 
to J Meaning 
First before-image for transaction 
Inserted record 
Abnormal termination 
Not used 
MIRAM, indexed 
—f Not used 


ZFHATC Transaction code; 2—6 EBCDIC Configured code identifying the 
current transaction; one to five 
alphanumeric characters, left- 
justified in field 

Fj 


ae 


ZFHACT TCT address 8—11 Hexadecimal Address of terminal control table 


(TCT) for terminal originating 

this transaction. Full-word aligned 
ZF#ATRID | Transaction id 
ZFHATMID | Terminal id 20-—23 


ZFHAIAP Initial action 24—29 
program 


ZFHACAP j Current action 
program 
ZFHADT Date-time 
of audit 


NOM OBR W —- © 





Nha WNH + Oo 





12—19 Data-time of initiation of this 
transaction, in the form: 


yy-mm-dd-hh-mm-ss 


Binary 





Hexadecimal Configured identification of network 


terminal initiating this transaction 





EBCDIC Program-name of first action program 


initiated for this transaction; 


one to six alphanumeric characters, 
left-justified 





30—35 EBCDIC Program-name of currently active 


action program 





36—43 Binary Date-time of writing this record to 
the audit file. in same form as 


transaction id 






Length of key in an indexed record; 


ZFHKLIDA | Key length 44--45 Binary 
set to O for a DAM record 


ZFHCNKN ea 46—47 Reserved for system use 


ZFHDLIDA } Data jength 48-—49 Binary Length of data portion of updated 
or record, or number of active update 
transactions 





ZFANAUT 








ZFHFNM File name 50—57 EBCDIC Logical name of data file being 
accessed by current action program; 
one to seven alphanumeric characters, 
left-justified 
NOTES: 
1. When records are written to the audit file for a UNIQUE action program, the transaction-code field contains OPEN, 


the initial-action-program field contains ZU#OPEN, and the current-action-program field contains the name of the 
UNIQUE module active at the time of audit. 


2. When the current action program is accessing a defined file, a prefix is written for each jogical record involved. In 
the prefix, the file-name field contains the LFD-name of a conventional user data file contributing a logical record 
(or part of one) to the defined record. It never contains the defined-file-name specified with the DFILE keyword. 


a ae hn al 
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3.8.6.3. COBOL Action Program Error Messages 


The COBOL error routine (CO@BJERR) records data in a message buffer that corresponds 
to errors contained in the canned message file. The IMS 90 user locates the message 
buffer in his dump and inspects it to find the cause of the error. The 4-byte message 
buffer, located at the address contained in general register 1 in the register save area of 
the program dump listing, contains the following: 


Hexadecimal 
Byte Content Description 
0 5B Canned message indicator (S$) 
1-2 nnnn Hexadecimal message number 
3 40 End-of-table indicator (blank) 


NOTE: 


The hexadecimal message number in bytes 71 and 2 is one of the following and 
corresponds to the numbered COBOL message shown. For the text of the message, its 
meaning, and suggested corrective action, refer to the OS/3 system messages 
programmer/operator reference, UP-8076 (current version). | 


Bytes 1—2 COBOL 
Content Message 
043A CEO03 
043B CE04 
043C CEO05 


3.8.7. Logical Record Lock Facility 


Logical record locks are used to protect records that are in the process of being updated by 
one transaction from concurrent updating by other transactions. Either of two logical lock 
options, lock-for-update or lock-for-transaction, is selected for a DAM, ISAM, IRAM, or 
MIRAM file via the LOCK parameter of the FILE section at configuration time. 


3.8.7.1. Lock for Update 


The lock-for-update option causes a lock to be imposed on a logical record when the 
record is retrieved from the file via the GETUP function. The lock prohibits access to the 
record by other transactions until it is unlocked. It does not prohibit further access in the 
Same transaction to the same record. The record is unlocked when one of the following 
events occurs in the transaction that imposed the lock: 


= The record is updated by means of the PUT or DELETE function. 


7 The action in which the lock was imposed or a subsequent action terminates with the 
termination-indicator set to N (normal transaction termination), A (abnormal 
transaction termination, voluntary), or the transaction abnormally terminates 
involuntarily. 
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= The action in which the lock was imposed, or a subsequent action, terminates with 
the termination-indicator set to E (external successor) or D (delayed internal 
successor) and the lock-rollback-indicator set to R (release all locks for pending 
updates), N (establish a new rollback point), or O (return to an old rollback point). 


=» An UNLOCK request is made for the file containing the record. 


3.8.7.2. Lock for Transaction 


The lock-for-transaction option causes a lock to be imposed on a logical record when it is 
retrieved from the file via the GETUP function or when it is inserted into the file via the 
INSERT function. The lock prohibits access to the record by other transactions until it is 
unlocked. It does not prohibit further access in the same transaction to the same record. 
The record is unlocked when one of the following events occurs in the transaction that 
imposed the lock: 


= The action in which the lock was imposed or a subsequent action terminates with the 
termination-indicator set to N (normal transaction termination), A (abnormal 
transaction termination, voluntary), S (abnormal transaction termination, voluntary, 
with snap dump), or the transaction is involuntary and abnormally terminates. 


= # The action in which the lock was imposed, or a. subsequent action, terminates with 
the termination-indicator set to E (external successor) or D (delayed internal 
successor) and the lock-rollback-indicator set to R (release all locks for pending 
updates). In this case, only those locks imposed as the result of GETUP requests and 
for which subsequent PUT or DELETE requests have not been issued are unlocked. 
Locks-for-transactions that fall into this category are called pending locks. If the lock- 
rollback-indicator is set to N or O, all locks are released. 


=» An UNLOCK request is made for the file containing the record. 


In single-thread configurations, when a transaction requests access to a locked record, the 
record is not accessed. Control returns immediately to the requesting action program with 
a status code of 3 (invalid request) and a detailed status code of 18 indicating that the 
record being accessed was locked by another transaction. 


In multithread configurations, the request for a locked record is queued until the record is 
unlocked. The record is then accessed before control returns to the requesting action 
program. 


The use of the lock-for-transaction option is closely related to the online file recovery 
feature of IMS 90. Consider an update transaction in which two records, A and B, are to 
be updated. Record A is in one file and B is in another, and, for both files, the lock-for- 
transaction option is specified. 


When record A is retrieved for updating (GETUP), a lock is applied. When updating is 
carried out (PUT), the lock is not released because LOCK=TR was specified at 
configuration time. Another transaction then attempts to access record A, but its request 
is queued to wait for the lock to be released. The first transaction then comes to an 
abnormal termination because it is unable to successfully update record B. 
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Online file recovery rolls back record A to its original state and then releases the lock. The 
second transaction then accesses the correct original version of record A. Record B is not 
updated. 


In general, lock-for-transaction in combination with online file recovery is used to ensure 
that all records that are to be updated in a transaction are either successfully updated or 
rolled back to their original state before any other transaction can access the records in 
the same order. Only files for which lock-for-transaction (i.e., LOCK=TR) or no locking (i.e., 
RECLOCK=NO) is specified can be rolled back by online file recovery. 


Since the capability exists for a transaction to lock multiple logical records and since a 
transaction must wait if it attempts to access a record that is already locked by another 
transaction, deadlock can occur in IMS 90. Deadlock can be avoided by choices made in 
the design of action programs. 


= First, deadlock does not occur if only a single record is updated in a transaction. 


= Second, deadlock does not occur if records are updated serially in a transaction (e.g., 
GETUP record A, PUT record A, GETUP record B, PUT record B, etc.) and all files for 
which updates are performed have the lock-for-update option specified. 


= Third, deadlock does not occur if all transactions that update a set of records update 
those records in the same order regardless of lock option. 


If deadlock occurs among two or more transactions as the result of improper file or action 
program design, no output other than the periodic status message will be sent back to the 
terminals that originated those transactions. A terminal operator, recognizing that output 
has not been returned in a reasonable period time, should cancel the transaction he has 
initiated. The cancel will free up all resources allocated to the transaction and may allow 
the deadlock to be broken. A sufficient number of cancellations also break the deadlock. 
This procedure is not desirable for most applications. To avoid it, the design rules must be 
followed or the user must have a clear understanding that action programs he designs 
must not reference the files in such a way as to cause deadlock. 


3.8.7.3. UNLOCK Function 

The UNLOCK function causes the release of record locks that have been imposed by file 
management for a transaction on a specific file. The UNLOCK function also makes ISAM, 
MIRAM, and IRAM files, held for a transaction pending the completion of an update, 
available for processing. 


COBOL Format: 


CALL ‘UNLOCK’ USING file-name. 


BAL Format: 


ee ene aman 
ZG#CALL 
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The UNLOCK function applies to both lock-for-update and lock-for-transaction imposed on 
DAM, IRAM, MIRAM, or ISAM files within the IMS 90 job. Normally, locks are released 
implicitly within IMS 90 as the result of action or transaction termination. The UNLOCK 
function should be requested only when the normal implicit release of locks does not meet 
the requirements of the application. 


Only the locks associated with pending updates for this transaction are released. An 
update is pending after a GETUP function but before either a PUT or DELETE function 
changes the record or some other event occurrs to indicate that the update will not be 
performed. 


lf the lock-for-update or lock-for-transaction option is specified for a DAM, IRAM, MIRAM, 
or ISAM file and an update of a record in that file is currently pending for a transaction, 
then an UNLOCK request from the transaction aborts the update by releasing the lock on 
the record. In the case of an ISAM file, the UNLOCK request makes the file, as well as the 
individual record, accessible for the processing of requests from other transactions. In the 
case of a DAM file, the UNLOCK request unlocks only the individual record. The file as a 
whole still remains accessible to other transactions. 


3.8.8. General File Processing Considerations 


© 3.8.8.1. Opening and Closing of Files 


All files defined in the file control table at configuration time are opened normally as a 
function of IMS 90 start-up and closed as a function of shutdown. Files also can be 
opened and closed from the master terminal via the master terminal commands, ZZOPN 
and ZZCLS. These master terminal commands cause IMS 90*file management to issue 
calls to data management to perform open and close functions. No capability exists to 
open and close files from an action program. For a detailed description of the ZZCLS and 
ZZOPN master terminal commands, see 5.2.2.6 and 5.2.2.7. 


3.8.8.2. Serial Use of File Descriptors 


Each file accessible to IMS 90 has a single file descriptor entry in the file control table. 
File management queues requests for each file and provides for servicing of the requests 
one at a time. 


3.8.8.3. Dynamic Allocation of !/O Areas 


|/O areas for user data files are preallocated in multithread IMS 90. In single-thread IMS 
90, |/O areas are allocated when required. Action scheduling acquires |/O areas, when 
needed, from main storage management as a function of action initiation. At most, one 
\/O area is allocated to a file at a given time. Once allocated, an I/O area can be used to 
Support a number of file functions for a number of different transactions. When no 

& potential or actual requests are outstanding for a file, the |/O area for the file is released 
by action scheduling to main storage management. 
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3.8.8.4. File Sharing @ 


All data files allocated to IMS 90 are accessible to all terminals in the configured network. 
An ISAM or MIRAM file (sequential mode) is allocated exclusively to an action for a series 
of sequential file operations when the SETL function is performed. It is deallocated either 
explicitly by the action by means of the ESETL function or implicitly at action termination 
by file management. 


Because of ISAM file updating procedures, such a file is exclusively allocated to a given 
transaction during the time that transaction has an update pending for the file. This 
exclusive allocation begins with the successful completion of a GETUP function and ends 
with the completion of a PUT or DELETE function to Carry out the update in the same 
action or with the termination of the action, whichever comes first. 


Exclusive use is forced to end at action termination to increase the sharability of the file 
(that is, to allow queued requests to be serviced). Although exclusive use of an ISAM file 
for update purposes must end with action termination, the lock on the record being 
updated can be held from one action to another. 


If a record is retrieved with a GETUP in one action and the update is to be completed in 
the following action, the following action must again retrieve the record with a GETUP 
before updating with a PUT or DELETE. This means that two retrievals of the record are 
necessary in a multiaction update. It is more efficient to Carry out updates of ISAM or 
MIRAM files in a single action. e 


3.8.8.5. Work and Record Areas for DAM File Access 


lf your DAM file resides on a fixed-sector disk (for example, a SPERRY UNIVAC 8416 or 
8418 Disk Subsystem), OS/3 data management requires that the length of the I/O area 
be some multiple of 256 bytes and half-word aligned. Moreover, to achieve device 
independence across disk subsystems, so that your program can access a DAM file on any 
disk used under OS/3, the same point holds — I/O areas should be multiples of 256 bytes 
in length. 


To ensure device independence in a BAL or COBOL action program that accesses DAM 
files, you should do the following: 


. If you are using a continuity data area (CDA) for record I/O, specify its length as a 
256-byte multiple via the CDASIZE configuration parameter in the ACTION section. 


= If your program varies the length of the CDA when succession is made from one 
action to another, the increment or the new output length you set in the PIB should 
be a 256-byte multiple. 


a lf the work area is used for record I/O, specify its length as a 256-byte multiple via 
the WORKSIZE configuration parameter in the ACTION section. 
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2 = If you specify a different work-area size for a succeeding action that is to access a 
DAM file, the increment placed into the WORK-AREA-INC field of the PIB should be a 
multiple of 256 bytes. The work-area increment is eae only in multithread IMS 

90. 


= The record-area parameter of any IMS 90 function call (GET, GETUP, PUT, DELETE, or 
INSERT) that your action program issues to process a DAM file must refer to an area 
whose reserved length is some multiple of 256 bytes on a half-word boundary. 


You have other considerations (such as record or block length, and the track capacity of 
the disk subsystem in use) to keep in mind in establishing work-area and record-area 
lengths for your action programs. For further details, refer to the current versions of the 
OS/3 data management user guide, UP-8068, or the data management programmer 
reference, UP-8159. 


3.8.8.6. Test Mode 


When a terminal has been put in the test mode (via the ZZTMD terminal command), any 
request to file management to change the contents of a file are only simulated. 
Specifically, no update, delete, insert, or append functions are performed when requested. 
Control is simply returned to the requesting transaction with a successful completion 
status code. 


_ A terminal can be put in the test mode after completion of a transaction, i.e, when not in 
an interactive mode. To revert to normal mode, the ZZNRM terminal command is used. 

Test mode is used in the training of new terminal operators in the use of update 
transactions. All terminal entries made by the operator are the same in test mode as in 

the normal mode except that no file modifications actually occur. Test mode also is used in 

the testing of newly written or modified action programs that perform file modifications. 


3.8.9. Common Storage Area Files 


You can increase file processing efficiency by making frequently accessed ISAM files 
resident in a special common storage area (CSA). This feature is especially useful for 
maintaining vital information used by many action programs. You must have adequate 
main storage to use this feature. It is not available for basic IMS 90, and the CSA is not 
accessible through UNIQUE. 


If you specify CAFILE=YES in the configurator FILE section, the designated ISAM file is 
loaded into the common storage area at start-up time. When you issue GET, GETUP, and 
PUT function calls, IMS 90 retrieves records from and makes updates to the CSA file, 
thereby reducing disk access. If you specify CUPDATE=YES to the configurator, updates 
are made to the disk as well as to the resident file. This saves disk accesses on reads but 
not on writes. However, if you omit CUPDATE or specify CUPDATE=NO, the disk file is not 
updated until IMS 90 shutdown, when the entire CSA file is written to disk. File locking 
and recovery functions are the same for the CSA file as for a disk file. 
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You can access a CSA file only in random mode. You use GET, GETUP, and PUT function © 
calls the same way for any ISAM file, but INSERT and DELETE functions are not valid. 

UNIQUE can access a CSA file through defined record management, but only through a 
supplement definition; you must not specify ASSUMES CONTROLLED ROLE IN UPDATE in 

the supplement definition. 


3.9. IMPLICIT AND EXPLICIT MESSAGE OUTPUT 


Normally, a message is sent to the designated logical destination from the output message 
area at action termination (CALL ‘RETURN’). This is smp/icit SHPES Implicit output takes 
several forms. It can be: 


= displayed or listed on the terminal initiating the transaction (Source terminal) or the 
terminal designated by the DESTINATION-TERMINAL-ID field of the OMA header; 


= listed on an auxiliary device attached to the source terminal or destination terminal; 
or 


= printed as continuous output at the source terminal or on an auxiliary device attached 
to the source terminal. 


If more than one message must be sent during an action, or if a transaction is to be 
initiated at a terminal other than a source terminal, this exp/icit output must be 
transmitted by means of the SEND function. © 


3.9: 1 Transmitting Messages via SEND Function 


The SEND function is typically used to send messages to terminals other than the 
originating terminal. This usage applies under both single and multithread IMS 90. It can 
also be used to initiate a transaction, typically a continuous output print transaction, at a 
distant terminal via output-for-input queueing (described in 3.10.2). In addition, the SEND 
function can designate the master terminal as the destination for messages without 
naming the master terminal in the program. This is useful for sending error messages to 
the master terminal when the originating terminal is not able to handle the error. 


COBOL Format: 
CALL ‘SEND’ USING output-message-area [master]. 
BAL Format: 


CALL pone eens cere ee eee ene eae 
ZG#CALL | 
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where: 


@ output-message-area 


Refers to a data-name (COBOL) or storage area (BAL) containing an output 
message header (in the format shown in Figures 3-10 and 3-11) and text. The 
output message area does not necessarily have to be the same as the OMA that 
is predefined for the action in the action control table. An output message can, 
for example, be explicitly sent from the work area allocated to an action. This 
area must be aligned on a full-word boundary. 


master 
Refers to a data-name or storage location that contains the value “M” indicating 
that this message is to be sent to the master terminal. | 


lf the master parameter is specified, and the data name referenced in the action program 
contains the value “M”, the message is sent to the master terminal. If this parameter is 
omitted, the message is sent to the terminal specified in the DESTINATION-TERMINAL-ID 
field of the OMA. If the data name referenced does not contain the value ‘’M”, an error is 
returned to the action program. This error is indicated by the value 3 (invalid request) in 
the STATUS-CODE field of the PIB and by the value 3 (incorrect parameter value) in the 
DETAILED-STATUS-CODE field of the PIB. The master parameter option is used with the 
output-for-input queueing process by placing the value “lin the AUX-FUNCTION field of 
the OMA header. This results in the generated message being queued as input for the 
master terminal regardless of the DESTINATION-TERMINAL-ID in the OMA header. 


@ An output message is not sent to the designated terminal by internal message control 
until the successful termination of the current action. If the transaction is terminated 
abnormally or canceled in the current action, all output messages generated in the action 
are deleted from the output message queue and no messages are delivered. A message 
indicating the reason for termination is sent to the originating terminal. After the output 
message is moved from the output message area and written to the output message 

queue, control is returned to the statement following the CALL statement. 


lf the SEND function is used frequently, disk queueing should be specified in the 
communications network definition. Refer to the IMS 90 system support functions user 
guide/programmer reference, UP-8364 (current version). If you use the SEND function, 
you must specify the UNSOL=YES parameter in the OPTIONS section of the configurator. 
To use output-for-input queueing, the CONTOUT=YES also must be configured. (See 
3.10.2.) 


3.9.2. Returns from SEND Function 


Following execution of the SEND function, IMS 90 notifies the action program of the 
success or failure of the request by placing binary values in the STATUS-CODE and 
DETAILED-STATUS-CODE fields of the program information block. If you specified 
ERET=YES to the configurator for this action program, the action program regains control 
at the instruction after the SEND function call and must interrogate these status bytes. If 
you did not specify ERET=YES, the program does not regain control in the event of 
@ unsuccessful completion of the SEND function and is abnormally terminated by IMS 90. A { 
3-line transaction termination message is sent to the system console. Transaction 
termination messages are documented in OS/3 system messages programmer/operator 
reference, UP-8076 (current version). f 
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IMS 90 returns the following values to the STATUS-CODE field of the PIB following the 
execution of the SEND function when ERET=YES is configured: 





Status Codes: 


O Successful 

1 and 2 Not used 

3 Invalid request 

4 and 5 Not used 

6 Internal message control error 


When the return made to the STATUS-CODE field of the PIB is 3 (invalid request), the 
DETAILED-STATUS-CODE field contains either 2 or 3. The value 2 indicates that 
unsolicited output or continuous output was not configured or that no process files were 
generated in your ICAM CCA. The value 3 indicates a parameter error has occurred. 


When the return made to the STATUS-CODE field of the PIB is 6 (internal message control 
error), the return made to the DETAILED-STATUS-CODE field is one of the following: 


Destination terminal is busy or on hold. 

Destination terminal is down; message is queued. 

Invalid destination terminal or auxiliary device specification 
No network buffer is available in the ICAM load module. 


Disk error 
Invalid length specification @ 


IMS 90 returns the value 2 (destination terminal busy or on hold) to the DETAILED- 
STATUS-CODE field only when the SEND function is issued to generate output-for-input 
queueing and one of the following conditions exists: 


“Om O1 B ® PD 


a Destination terminal is in interactive mode. 
a Destination terminal already has an input message on queue. 


cf A ZZHLD terminal command has been entered at the destination terminal or a 
ZZDWN command for this terminal has been entered at the master terminal: 
therefore, it is logically down to IMS 90. 


= The destination terminal is marked physically down to ICAM. 


These are not permanent conditions; the output message header content is not invalid, 
and the same message may be retransmitted successfully at some later time. 


IMS 90 returns a DETAILED-STATUS-CODE of 3 when an action program attempts to send 

a message (via CALL SEND) to a destination terminal that is physically or logically down. 

The message is still queued for that terminal and is automatically transmitted when the 

terminal comes back up. If the destination terminal is down and is alternated (via the 

ZZALT command) to another terminal in the IMS network, no error is returned to the _ 
action program. The message is sent to the alternate terminal. If the alternate terminal is @& 
also down, a DETAILED-STATUS-CODE of 3 is returned to the action program. 


UP-8614 Rev. 1 SPERRY UNIVAC 0S/3 3-85 


IMS 90 APPLICATIONS Update A 


@ When IMS 90 returns the DETAILED-STATUS-CODE value 4 (invalid destination terminal 
or auxiliary specification) after the SEND function, the content of the OMA header is not 
valid, and efforts to retransmit the output message will continue to be unsuccessful. One 
of the following errors is likely to have been made in your action program: 


= The DESTINATION-TERMINAL-ID specified in the OMA header is not a _ valid 
configured terminal identification. 


= The AUXILIARY-DEVICE-ID specification is invalid. 


e® The AUX-FUNCTION byte contains the hexadecimal value C3, F3, or F7, indicating 
that Continuous output is requested. Continuous output must be the smpi/icit output 
from an action program requesting it; it can not be transmitted via the SEND function. 


3.10. PRINT TRANSACTIONS USING CONTINUOUS OUTPUT 


When your installation applications include a need for printing at one of your interactive 
network terminals, you can easily implement print transactions by using the optional | 
continuous output feature. You can direct the printing to be done at the terminal that 
originates the print transaction or cause the printing to be initiated at a different terminal 
- which can be an unattended terminal, or even a receive-only or output-only interactive 
device. 


© Continuous output is an option you select at configuration time via the CONTOUT keyword 
parameter in the OPTIONS section and is available for both multithread and single-thread 
operations (but not for basic IMS 9Q). It is not limited to normal interactive processing, but 
can be used in the batch processing mode - online for production or offline for testing. 
When you specify the use of continuous output at configuration time, an additional 
internal message control component is included in your IMS 90 load module by the 
configurator. 


The CONTOUT specification also causes the automatic inclusion of IMS 90 support for 
unsolicited output. The module giving this capability is used in continuous output to 
Support the ability to initiate a print transaction at a destination terminal other than the 
originating terminal. For this, you use the output-for-input-queueing feature via the SEND 
function. Use of the continuous output feature also requires a resident ICAM. 


The terminals and auxiliary devices to which continuous output can be directed by your 
printing transactions are: 


=” DCT 500 Data Communications Terminals operating tn teletypewriter mode 
2 DCT 1000 Data Communications Terminals 


m= TELETYPE* Modules 28, 33, 35, 37, and 38 


*Trademark of Teletype Corporation 
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= Auxiliary devices at the UNISCOPE 100 or 200 Display Terminal or Universal Terminal 
System 400 (UTS 400). These are: 


- Communications Output Printers (COPs) 


Terminal Printers (TPs) 
—- Model 610 Tape Cassette System (TCS) 


8406 Diskette Subsystem 


Note that these are the interactive devices supported by ICAM; the DCT 1000 operating as 
a batch (card-oriented) terminal or any other batch terminal is not usable for continuous 
output. 


In addition, ICAM supports a UTS 400 feature called screen bypass, which is addresssable 
only for output (3.10.3). 


The following paragraphs describe how you can use the continuous output option as an 
action programmer; sample action programs are presented in 3.16 to further illustrate the 
points developed here. 


3.10.1. Generating Continuous Output 


A print transaction must direct all its continuous output to the same terminal, i.e., the one 
specified in the SOURCE-TERMINAL-ID field (ZA#ISTID) of the input message area header. 
When you do not desire continuous output at the terminal initiating the transaction, you 
direct a print transaction to be initiated at another terminal, using the output-for-input- 
queueing feature explained in 3.10.2. 


Whether you are transmitting continuous output at a primary device or at an auxiliary 
attached to it, you generate only one continuous output message per action; this message 
must be your implicit output and cannot be generated via the SEND function. You are not 
restricted from using the SEND function for other unsolicited output, however, nor are you 
restricted from sending other output to the primary device via the SEND function. 


3.10.1.1. Output Message Header Fields for Continuous Output 


You specify that an output message is for continuous output by the value you send in the 
AUXILIARY-FUNCTION field (the first byte of the AUXILIARY-DEVICE-ID field) in the OMA 
header. When your continuous output is to be transmitted to a COP, TP, tape cassette, or 
diskette attached to the primary device at which your program is initiated, you must also 
set the second byte of this field (the AUX-DEVICE-NO) to specify which of the configured 
auxiliary devices is to be used for data transmission; otherwise, set the AUX-DEVICE-NO 
byte to binary 0. Table 3-16 summarizes the settings of the AUX-FUNCTION byte for 
normal and for continuous output. 
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When you are transmitting to a COP, TP, cassette, or diskette auxiliary device, you can 
specify print-transparent mode. In this mode, although your output goes through the logic 
of the primary device, its format is independent of the format on the screen. Whatever 
DICE sequences you then include in your message apply to these auxiliary devices and the 
cursor return characters normally inserted by the logic of the terminal are not transmitted 
to the auxiliary interface. Thus, the length of lines written to the auxiliary device is 
independent of the line length of the screen. 


When using print-transparent mode with a UNISCOPE 100 display terminal, you should 
make sure that your output message does not exceed the capacity of the screen. If it does, 


lost. The same consideration also applies to the UNISCOPE 200 and UTS 400. However, 
their larger screen capacity makes wraparound a less likely occurrence. 


In print mode you apply your DICE sequences for the screen, and the message printed on 
the auxiliary device will have the same format as the screen. For further details on print 


mode and print-transparent mode, refer to the current versions of the UNISCOPE 
programmer reference, UP-7807 and the UTS 400 programmer reference, UP-8359. 


Table 3—16. Settings for Auxiliary Function Byte of Output Message Header (Part 1 of 2) 


Input/Output Options Contents of AUX-FUNCTION Field 


: S Inhibit No Continuous Output 
‘ a3 pace 
Primary | Auxiliary Bice ressiai Space 
e Suppression 
px | of 


. Print Transparent 





Ti 


ol 
7 











~J 
TI Th 


po 


Print Form (ESC H) 


¢) 
N 
OC 
N 


Transfer All (ESCG) 


~~ 
~ 


i 
ca 


Suisse! 
a 
<a 
a 
ae 
Lasse 
ae 


Transfer Variabie 
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Transfer Changed X 


{ESC E) 
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Y 
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Table 3—16. Settings for Auxiliary Function Byte of Output Message Header (Part 2 of 2) 


input/Output Options Contents of AUX-FUNCTION Fieid 


Inhibit No Continuous = 
Space 
Suppression 


a es ce 


Xx 
Search and Read 
oy 












S 
Paina: Auxiliary cele 






Suppression 





| Report Address Address 


Backward One 
Block 

Search and 
Position 


When you choose print or transfer options, you may either allow or inhibit space 
suppression in output messages. If you do not specify the inhibit space suppression option, 
the remote device handler (RDH) suppresses nonsignificant spaces. If you do specify the 
inhibit space suppression option, the RDH changes all spaces to DC3 characters making it 
necessary to strap the COP or TP devices to space when they receive a DC3 character in 
the text data. 





In addition to print and print transparent options, the following print options directed to the 
UTS 400 terminal printers, cassette, or diskettes can be specified with or without the 
inhibit space suppression option. Unless the inhibit space suppression option is specified 
with each of these print options, nonsignificant spaces are suppressed. 


Y ia Print form (ESC H) sends to the terminal printer, cassette, or diskette all of the 
unprotected characters and protected characters from the start-of-entry (SOE or home 
position) to the cursor. Spaces are substituted for protected data. Field control 

A characters (FCC) are suppressed. 


= Transfer all (ESC G) sends to the terminal printer, cassette, or diskette all characters 
from SOE to cursor including FCC sequences. 


= Transfer variable (ESC F) sends to the terminal printer, cassette, or diskette only the 
variable (unprotected) characters between the SOE and cursor including FCC 
sequences. 


= Transfer changed (ESC E) sends to the terminal printer, cassette, or diskette only the 
changed characters (or altered fields) between the SOE and the cursor including FCC 
sequences. 
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© Several options are available to read and write, search, or position data on cassette and 
diskette auxiliary devices. To use these options, your action program must move both the 
desired option character code and the auxiliary device number to the AUX-FUNCTION and 
AUX-DEVICE-NO fields of the output message header respectively. Your action program 
can then issue either a SEND or RETURN function to transmit an output message to the 
auxiliary device, i.e., write a block of data to the cassette or diskette. In this way, your 
action program may also read a block of data from the cassette or diskette, display it on 
the UNISCOPE screen or position a cassette/diskette at a specific block. Note that the 
SEND function cannot be used to transmit continuous output options. 


In some cases, input from the auxiliary device may be expected as a result of output from 
your action program. Cassette/diskette input then appears on the terminal screen but is 
not transmitted to your program unless you press the transmit key at the terminal. 
Otherwise, you can set the AUTO TRANSMIT switch on the tape cassette or diskette 
system before data is transmitted from the cassette/diskette to the terminal and the input 
data is automatically supplied to your action program. When your action program receives 
input resulting from a previous output to the auxiliary device, the auxiliary device number 
from the OMA is returned to the IMA. Figure 3-15 illustrates the data flow between your 
action program and the cassette/diskette auxiliary devices. 


© CASSETTE 


ACTION 
PROGRAM 


DISKETTE 


ACTION 
UNISCOPE PROGRAM 
OR UTS 400 





Figure 3—15. Action Program Interface with Cassette/Diskette 
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The output options print mode, print transparent, print form, transfer all, transfer variable, 
and transfer changed can be used with cassette/diskette; however, the print form, transfer 
all, transfer variable, and transfer changed may be used only when the primary device is a 
UTS 400 terminal. 


There are four input options used with cassette/diskette: read, read transparent; search 
and read; and search and read transparent. The continuous output feature must be used 
with any of these input options: 


The read option reads a block of data from the cassette/diskette to the terminal 
screen. When you set this option, your action program should not contain text in the 
OMA and the text length field should contain 4. 


The read transparent option reads a block of data from the cassette/diskette, and the 
remote device handler deletes the SOE cursor sequence, carriage return codes, and 
DICE codes. If the data is transmitted to your action program, the IMA message text 
will then be identical to the OMA text originally written to the cassette/diskette. 


The search and read option reads a block of data from the cassette/diskette only if a 
search argument specified in the message text of the OMA is satisfied. When the 
argument is satisfied, the block of data is moved to the terminal screen. Your search 
argument may be in one of three search and read modes. (See Table 3-17 for their 
formats.) When you use the search and read options, the only contents of the OMA 
message text should be the search argument in the mode you choose. 


The search and read transparent option performs the same function as the search 
and read option except the remote device handler removes all DICE sequences, SOE 
cursor sequence, and carriage return characters from the input message. 


Two other options available for cassette/diskette on continuous and noncontinuous output 
are the search-and-position and backward-one block options. 


The search-and-position option positions the cassette/diskette to the block requested 
in the search argument that your action program supplies in the output message text 
of the OMA. (See Table 3-18 for formats used in describing the search argument.) 
Your OMA message text may not contain any other entries. 


The backward-one-block option repositions the cassette/diskette one block in reverse. 
The AUXILIARY-DEVICE-ID field must be set and the TEXT-LENGTH field in the OMA 
must be 4. 
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Table 3—17. User Message Text for Searching Cassette/Diskette 


Search Argument Format Search Type 


Ataaaa Mode search to position the tape to a particular 
or address and then read one block, where A, 1, or 
1taaaa a is constant, and: 
or t 
ataaaa Is the track address (1 or 2). 


aaaa 
Is the address where the tape is 
to be positioned. 


Btaaaa/c... Mode search to position the tape to a particular 
or address, search for a specific character string, 
2taaaa/c... and read one block, where B, 2, or b is constant, 

or and: 
btaaaa/c...c_ ‘ 


is the track address (1 or 2). 


aaaa 
Is the block address. 


.c 
Is the character string. Up to 
16 characters can be specified. 


Mode search to find the specified character 
string, where C, 3, or c is constant, and: 


t 
Ils the track address (1 or 2). 


C126 
Is the character string. Up to 16 
characters can be specified. 

The search starts at the present 
tape position. 





Table 3—18. User Message Text for Search and Positioning 


Search Argument Format Search Type 


@taaaa Mode search to position the tape, where: 
or @, 0, or (grave accent mark) is constant, 
Otaaaa and: 
or t 


‘taaaa Is the track address (1 or 2). 


SSSS 
Is the address where the tape 
is to be positioned. If specified 
as OOOO, the tape is rewound. 





3-91 
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One additional option, the report address, displays the address of the cassette/diskette 
device on the terminal screen. Because input is expected after this action ends, the report 
address option cannot be used with the continuous output feature. The OMA TEXT- 
LENGTH field must contain the value 4. 


In addition to making the required settings of the AUXILIARY-DEVICE-ID field of the OMA 
header, you also can insert into the 4-byte CONTINUOUS-OUTPUT-CODE field an optional 
alphanumeric character string that identifies the continuous output message you have 
generated. This optional code is returned by IMS 90 in the first four bytes of a 5-byte input 
message created for processing by the external successor designated by this action 
program. If you do not specify a code, the first four bytes of the input message generated 
by IMS 90 for your external successor contain binary zeros. 


The CONTINUOUS-OUTPUT-CODE field of the OMA assumes special importance when 
you use any of the four input options or the report address option. When you use these 
options, a delivery notice is returned only if it represents a delivery notice error; otherwise, 
there is no input to the successor action program until a message is transmitted from the 
screen or, in the case of a screen bypass terminal, until the auto-transmit feature is used 
to transmit the message from the cassette/diskette device. 


When using a screen bypass terminal, you must first set the control page for that terminal 
to take advantage of the auto-transmit capability. If this is not done for any of these five 
input options and a successful delivery notice is returned by the cassette/diskette device, 
the screen bypass terminal will be “hung” in interactive mode waiting for input that is 
never sent to it. © 


Because a successor action program may receive as input either a delivery notice error or 
an input message, the CONTINUOUS-OUTPUT-CODE used in the preceding continuous 
output message should be distinguishable from the first four characters of any possible 
input message being read from the cassette or diskette. In this way the successor action 
program determines what type of input message it receives (i.e. delivery notice error or 
input text) and processes it accordingly. In either case, the successor action program must 
be capable of handling both delivery notices and standard input messages. 


3.10.1.2. Terminating Print Transactions 


To continue printing, your action program terminates in external succession, naming itself 
or another action program in the SUCCESSOR-ID field of the PIB and passing (via the 
continuity data area) such information as is required to prepare the next of the continuous 
series of output messages. A program that creates a message for continuous output can 
terminate with only external succession. Immediate internal succession is not invalid but 
does not cause the output message to be sent. Any other form of succession causes IMS 
90 to abnormally terminate the transaction, and the message generated is not transmitted. 


On the other hand, the routines of your program that do not create continuous output are 

not restricted to terminating in external succession. They can use external succession or 

any other form of succession that is appropriate and typically they are routines that 

receive control as a result of your encountering errors or conditions relating to interruption _ 
or resumption of the continuous printing transaction. Normal termination is appropriate 

when you have completed all printing, for example. 
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© 3.10.1.3. Delivery Notice Scheduling 


A program named as the successor to a program that creates continuous output also must 
be prepared to accept and process the 5-byte input message created by IMS 90. The 5- 
byte message indicates that ICAM has delivered your output message to its destination for 
continuous printing and has received an acknowledgement (the delivery notice) from the 
destination terminal. 


The first four bytes of this input message contain either an optional 4-byte code you 
moved into the CONTINUOUS-OUTPUT-CODE field of the OMA header before you 
terminated, or binary zeros. If you have specified lowercase-to-uppercase translation or 
editing for input messages for the action receiving this input (via the ACTION section of 
your configurator input), this 4-byte field can vary from the CONTINUOUS-OUTPUT-CODE 
field as generated in the previous OMA. 


The fifth byte of the new input message contains a value indicating the completion status 
of the output message. If the last output message was successfully delivered, you proceed 
to generate anocher or to terminate normally if you have no more to produce - possibly 
with a message output to the primary device to notify the terminal operator of the 
completion of the continuous print transaction. 


However, if you are printing continuous output on preformatted forms — paychecks, for 
example - and do not want any printable characters output after normal termination, your 
last output message should comprise null characters. The point here is that if you do not 

© put out some message when you terminate normally, then IMS 90 issues one of its 
canned messages by default (ACTION COMPLETE, or TRANSACTION COMPLETE) to the 
primary device after you call the RETURN function. If your printing is not being performed 
on a COP or TP, the canned IMS 90 message is printed on your form. (You may also need 
to program similar interceptions of the error messages that IMS 90 generates under 
certain conditions.) 


When the completion status code in the fifth byte of the input message _ indicates 
unsuccessful output, you have a number of recovery options, depending on your 
application, that are discussed further in the following paragraphs. In planning recovery, 
however, it is important to realize the difference between polled and unpolled devices with 
respect to unsuccessful delivery notices. 


Only the DCT 1000, UNISCOPE 100 and 200, and UTS 400 terminals are polled devices 
that actually transmit an acknowledgment to ICAM. The nonpolled devices (the TELETYPE 
and DCT 500 terminals) do not do so; unless a line-down condition prevents it, a delivery 
notice is generated automatically for messages sent to these latter devices, and it always 
indicates successful output completion, regardless of the true condition of the output 
message. Only a line-down condition causes an unsuccessful completion status. 


IMS 90 always receives a successful completion status from ICAM when a message has 
been delivered to nonpolled devices and, therefore, reschedules your program with a 
successful delivery notice code in the fifth byte of the input message that it creates for 
you. For these reasons, when completing your continuous output or recovery in cases of 
nondelivery in a critical part of your printing application, you should avoid using nonpolled 
devices. 
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3.10.1.4. Recovery Considerations with Delivery Notice Scheduling ® 


Recovery and restart processing are the responsibility of your action program; IMS 90 
merely gives your printing transaction the means to perform recovery by notifying you of 
the success or failure of each continuous output message. For example, your successor 
action program keeps track of your continuous output in case any restarts are necessary. 
When unsuccessful completion status is returned, you may note these occurrences and 
continue as if successful - or terminate the transaction, to be restarted at some later time 
at the appropriate point. If your continuous output is directed to an auxiliary device, you 
send a regular output message to the primary device, indicating the need for assistance. 
You might terminate with external succession, awaiting an input message from the 
terminal to trigger the continuation of your print transaction. In any case, your action 
program must be prepared to accept actual input from the destination terminal as well as 
the delivery notice input message generated by IMS 90. Your terminal operators should be 
appropriately trained in these recovery procedures. 


Both operator-entered input and delivery notice input can cause attempts to schedule your 
action program. If operator-entered input exists, IMS 90 processes that input and 
eliminates the delivery notice from the previous continuous output message. You should, 
therefore, code your action program to handle keyboard input that can end, temporarily 
break, and resume the continuous output transaction. The best way to interrupt 
continuous output is to use function keys as keyboard input. Function keys are faster to 
use because they are never locked even when all remaining keys on the terminal are 
locked. 


When a message is unsuccessfully sent to an auxiliary device, only that device is marked 
down; output can still be addressed to the primary device. Your successor action program, 
which receives the error notification, can send an error message to the primary device and 
allow input from that terminal to cause continuation of the print transaction. Your recovery 
procedure should take into account the fact that IMS 90 has canceled the output message 
from the queue. 


On the other hand, if an error occurs while your continuous output message is being sent 
to a polled primary device, it also is likely that an error message will be unsuccessfully 
delivered, and more likely that you will need help from the terminal operator or a 
technican to get the terminal in working order. In this situation, your action program might 
terminate the print transaction altogether, recording the point at which the error was 
encountered. A later initiation of this print transaction could start the printing at the point 
recorded. 


An alternative in this situation is to send an unsolicited output message to another 
terminal, indicating the error and requesting assistance. (This could be the master 
terminal.) The action program could then terminate with a null message. When the out-of- 
order terminal is back in operation, the operator can enter an input message from the 
reinstated terminal to activate the successor action. The operator should not enter a 
terminal command. (This is also a recommended procedure when printing at a screen 
bypass terminal.) 
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Table 3—19. Output Delivery Notice Status Codes 


Primary Devices Addressed 
Poiled Nonpoltted Corresponding 
UNISCOPE Labels in Hexadecimal 
and UTS 400 DCT 1000 DCT 500 TTY TCS DSECT @) Value 
Successful output Yes Yes Yes, Yes, “TM#TDNEM 81 (2) 


completion regardless regardless 
of delivery of delivery 


Line down or TM#TDLNO | 
disconnected. 

Message deleted 

by IMS 90. 





Terminal TM#TDDNA 
marked down. 

Message deleted 

by IMS 90. (3) 


Auxiliary TM#TDNAX 
device down. 

Message deleted 

by IMS 90. 

Output may be 

addressed to the 

primary device. 


Missing or TMFTE DST 
invalid destination 

or auxiliary spec. 

in header 


No ICAM TM#TENBA 
network buffer 
available (S) 


40 @) 

342) 

e5@ 

a6 2) 
Invalid output TM#TEILG 87 2) 
buffer length 


NOTES: 


1) A BAL action program should access the labels in the TCS DSECT instead of testing the hexadecimal values in the input 
message directly. The hexadecimal values shown in the table can change in future releases, but the DSECT labels will 
remain the same. 


(2) The hexadecimal value 81, indicating successful output completion, is translated to the character A if the lowercase-to- 
uppercase translate option is specified for messages input to the successor action. Similarly, the hexadecimal values 84 
through 87, indicating error conditions, are translated to the characters D through G if the translate option is specified. 


3) When a terminal is marked down, input solicitation (potling) by ICAM continues automatically. When ICAM receives input 
from the down terminal, that terminal is marked up, and the input is scheduled for IMS 90. 


Refer to Table 3-15 for UNISCOPE and UTS 400 auxiliary device condition codes that are ORed with TM#TDNAX. 


© ® 


If this condition exists, a user action program can try to resend the fast continuous output message. 
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In the fifth byte of the input message, IMS 90 provides you with the output delivery notice © 
status code it receives from ICAM. The hexadecimal values of the code are listed in Table 

3-19 or 3-20: these tables also list the corresponding labels in the ICAM transaction 

control section (TCS) DSECT, TM#TCS. If yours is a COBOL action program, you must test 

for this hexadecimal value in the fifth byte of the input message, as shown in the sample 

program PRINT in 3.15.3. 


However, a BAL action program should be coded to access the labels in a TCS DSECT it 
has generated inline for this purpose, instead of testing for the hexadecimal value directly 
in the input message. The reason for this is that these hexadecimal values (which are 
equate (EQU) values for each DSECT label) can change in future OS/3 releases (but the 
ICAM DSECT labels always remain the same). If you access the labels, you have only to 
reassemble your BAL action program with each new release to be sure that your DSECT is 
current; otherwise you must change your code and reassemble. 


Note also that if you specify TRANSLAT=YES for the action, ICAM DSECTs may not be 
used to evaluate delivery notice status codes because status codes will be changed by the 
translate routine. (See note 2, Table 3-19.) 


You call the ICAM procedure TM#DSECT, using the operand TCS, to generate the TCS 
DSECT inline when your BAL program is assembled. Figure 3-16 shows the delivery 
notification error code labels contained in the DSECT. 


By using output delivery status codes, continuous output users can apply recovery ss 
procedures when output message errors are detected at message queueing time as well © 
as delivery time. Errors with hexadecimal values 84 through 87 (Table 3-19) are 

discovered at the time the output is queued. All others are detected at the time the output 

is delivered to the terminal. Reasons for output message errors are: 

= a missing or invalid destination in the output message header; 


# an invalid output buffer length in the output message header; 


no ICAM network buffer available; or 


i a disk error occurred. 


If the no-ICAM-network-buffer-available status exists, a user action program can try to 
resend the last continuous output message. 
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TM#TDDNA 


TM#TDNAX 


* 


x 


TM#TDDS1 


* 


* 


TM#TDDS2 


* 


* 


TM#TDDS3 


* 


TM#TDDS4 


TM#TONEM 


* 


TM#TDLNO 


TM#TEDST 
TM#TENBA 
TM#TEDER 
TM#TEILG 
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TERMINAL MARKED DOWN 
MESSAGE HELD 
AUXILIARY DEVICE DOWN 
MESSAGE HELD 
OUTPUT CAN STILL BE SENT TO 
. PRIMARY 
UNISCOPE AUXILIARY STATUS ONE 
MESSAGE HELD 
GOOD STATUS BUT READ/WRITE 
. FUNCTION INOPERATIVE 
UNISCOPE AUX STATUS TWO 
MESSAGE HELD 
. PRINTER OUT OF PAPER, 
INOPERATIVE OR IN TEST MODE 
UNISCOPE AUX STATUS THREE 
MESSAGE HELD 
. TAPE CASSETTE END-OF-TAPE 
UNISCOPE AUX STATUS FOUR 
MESSAGE HELD 
NO RESPONSE FROM DEVICE WHEN 
ATTEMPTING TO READ BLOCK OF 
TAPE 


SUCCESSFUL OUTPUT COMPLETION 


LINE DOWN/DISCONNECTED 

MESSAGE HELD 
MISSING OR INVALID DESTINATION 
NO ICAM NETWORK BUFFER AVAILABLE 
DISK ERROR OCCURRED SERVICING SVC 


. ENVALID OUTPUT BUFFER LENGTH 








NOTE: 


The contents listed with each label in the DSECT indicate that the message is being held by ICAM. 
However, IMS 90 deletes these messages from the queue. 


Figure 3—16. Portion of ICAM TCS DSECT in BAL Action Program Showing Delivery Notification Error Codes 
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3.10.2. QOutput-for-Input Queueing via the SEND Function 


When you want to print continuous output at a terminal other than the one initiating the 
transaction, you do so by means of the output-for-input-queueing option, which causes an 
output message transmitted via the SEND function to be queued as an input message at 
the destination terminal instead of being output there. You do not transmit continuous 
output by this method but cause a transaction to be initiated at the destination terminal, 
which generates and prints continuous output. For example, the transaction you initiate at 
the originating terminal can create the records you want to be printed and write them to 
an indexed sequential file. The last stage of this transaction generates an output message 
for input queueing at the terminal where the printing is to be done; the transaction 
initiated by this input message reads the ISAM file sequentially and prints the messages 
as continuous output, using delivery notice scheduling for recovery (3.10.1.4). 


Table 3—20. UNISCOPE and UTS 400 Auxiliary Device Condition Codes 


Hexadecimal Hexadecimal UNISCOPE 
Auxiliary Device Value Value when or UTS 400 
Condition Equated ORed with Auxiliary 

to Label ™#TDNAX®) Status 


Ready (good) status TM#TDDS1 
but COP/TP write 
function inoperative 


Device out of paper, TM#TDDS2 02 42 2 
inoperative, or in 
test mode 


Device is not TM#TDDS4 
responding; it 

may be disconnected, 

or a read of unwritten 

tape may have occurred. 


NOTES: 





) Your action program should access the labels in the DSECT instead of testing the 
value directly, because the equate (EQU) value for each label in the DSECT can vary in 
future releases. The labels will always remain the same. 


@) The label TM#TONAX represents the auxiliary-device-down condition. (Refer to Table 
3-19.) 
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_ This output message is queued as input from the destination terminal. Its text must begin 
with the transaction code that causes activation of the print transaction. The name of the 
file to be read by this transaction at the destination terminal must be specified to the 
configurator via the FILES or DFILE parameter as specified for the corresponding file in the 
ACTION section for the originating transaction, which creates the records. 


Your action issuing the SEND function directs that its output be queued as an input 
message from the destination terminal by setting the hexadecimal value C9 in the AUX- 
FUNCTION byte of the AUXILIARY-DEVICE-ID field of the OMA header; it does not use the 
CONTINUOUS-OUTPUT-CODE field. You must supply the configured identification of the 
terminal addressed in the DESTINATION-TERMINAL-ID field. 


If the destination terminal is in interactive mode when your SEND function is executed, or 
if it already has an outstanding input to be scheduled for it, the output message you are 
sending cannot cause input scheduling. In this event, your action program issuing the 
SEND function receives an unsuccessful STATUS CODE in the PIB on return from the 
SEND. (Refer to 3.9.2.) | 


When you generate an output message and request that it be queued as input from 

another terminal, IMS 90 validates your header and the status of the destination terminal. 

Any errors encountered at this point are indicated to your originating action program by 

the returns made to the PIB after execution of the SEND function. However, any errors 
encountered in the text of the message (such as an invalid transaction code or some error 

. found in the text by the print transaction scheduled to process the message at its 
® destination) are reported by output to the destination terminal. The action program 
creating the output message is not informed of these errors by IMS 90. If your application 

requires such feedback to the originating terminal, you must provide for it specifically by 
instructions to the destination terminal operator or in your coding of the print transaction. 


The message generated is queued immediately to the destination terminal. Therefore, if 
your action program that directs its output to be queued as input to another terminal via 
the SEND function terminates abnormally after issuing the SEND function, the output still 
generates a new transaction. In single-thread IMS 90, only one output message is created 
in any one action. Also, an action program running under single-thread IMS 90 and 
generating this type of output message must not terminate in delayed internal succession; 
to do so causes IMS 90 to abnormally terminate the action program. External succession 
can be appropriate in certain circumstances and is allowed; however, normal termination 
is generally considered adequate. 


For a sample COBOL action program that illustrates output-for-input queueing, refer to 
3.15.4. 
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3.10.3. Addressing a Screen Bypass Device 


A UTS 400 screen bypass device is defined to ICAM as a logical terminal, but since it is 
physically a separate buffer that can have a telecommunications printer attached to it, it 
has no input medium. It is uniquely addressable for output and cannot be used to enter 
input. Thus, in the IMS 90 environment, the only way to access a screen bypass is to use 
the output-for-input queueing feature. That is, another terminal in the IMS 90 network can 
generate an output message via CALL SEND to be processed as input on behalf of the 
screen bypass device. The transaction initiated by that message can then be a simple 
transaction or a print transaction using continuous output. Neither interactive transactions 
or switched messages can be processed by a screen bypass device because both require 
input. 


3.11. DISCONNECTING A LINE FROM AN ACTION PROGRAM 


The line disconnect feature allows an action program to disconnect a single-station dial-in line 
following the delivery of its output message to enable another terminal to dial in on the same 
line. To use the line disconnect feature, you must include the continuous output capability in 
your configuration by specifying CONTOUT=YES in the OPTIONS section. This feature is 
available only in a dedicated ICAM network, not a global network. 


To disconnect a line after message transmission, the action program must: 


= place a continuous output flag (X‘C3’) in the AUX-FUNCTION byte (ZA#OAUxX field) of 
the output message header; and 7 


= specify external succession with ‘HANGUP’ as the successor by setting the 
TERMINATION-INDICATOR (ZA#PSIND field) in the PIB to C’E’ and the SUCCESSOR- 
ID (ZA#PSID field) to C'HANGUP’. 


HANGUP is an action program supplied by IMS 90 that terminates with a special code 
causing IMS 90 to issue a line release/line request sequence to ICAM to disconnect the 
line. 


After the output message is sent, no further input is required from the terminal operator. 
IMS 90 waits for ICAM notification of message delivery before scheduling the external 
successor, HANGUP. In this way, delivery of the message prior to the line disconnect is 
ensured. 

3.12. SNAPSHOT DUMP PROCESSING 


IMS 90 provides a snapshot dump under four conditions: 


# An action program voluntarily terminates by moving an ‘S’ into the 1-byte 
TERMINATION-INDICATOR field of the program information block (See 3.6.1.4.) 


= An action program terminates due to program check 


= An action program abnormally terminates due to timer-check (time-out due to loop in 
action program) 
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& = An action program or subprogram issues a SNAP function call; i.e. a CALL ‘SNAP’ 
statement in a COBOL action program or the ZG#CALL macro in a BAL action 


program. 


IMS 90 places the snapshot dump in the spool file, from which it can be printed 
immediately without terminating the IMS 90 job. | 


3.12.1. Voluntary and Abnormal Snaps 


Every IMS snap dump contains header conformation regarding the terminated action 
program and why it failed. 


The next section of the snap dump contains registers. Here you'll find one or two sets of 
registers depending on the reason for the snap dump. 


If you voluntarily terminated your action program by moving S to the TERMINATION- 
INDICATOR field of the program information block, the snap dump contains one set of 
registers. These are IMS registers. They are of little use to an action programmer. To find 
the registers belonging to your action program, you must go to relative location PIB + 40, 
where there is a full word forward pointer. This word is the address of the SAVE area that 
contains your action program's registers. Go to this address and advance three full words. 
The next full word is register 14, then 15, then registers O-12. 





If, on the other hand, IMS terminated your action program due to a program check or time- 
out, the snap dump contains two sets of registers, IMS and user action program registers. 
The user registers are labeled so they are easily identifiable. In addition, a duplicate set of 
user registers can be found at location PIB + 44 (subscript 16). At this location in the 
program information block you'll find the 16-byte program status word (PSW) indicating 
the address of the instruction immediately following the one that caused the abnormal 
termination. Also, right after the PSW are the action program's 16 registers (O-F). 


Your action program must never issue the SNAP or SNAPF supervisor macros; to do so 
causes IMS 90 to terminate. 
3.12.2. Call Snaps 


The SNAP function allows an action program to display up to six noncontiguous main 
storage areas in hexadecimal. Output is to the printer. 


COBOL Format: 


CALL ‘SNAP’ USING item-1 next-item-1[...item-6 next-item-6]. 
where: 
item-1...item-6 
_ Is the data name of the beginning of the area to be displayed. 
next-item-l...next-item-6 


Is the data name of the end of the area to be displayed. 
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BAL Format: 
ZG#CALL SNAP (start-addr-l,end-addr-1[,...start-addr-6,end-addr-6] 
where: | 


Start-addr-l...start-addr-6 . 
is the start address of the area to be displayed. 


end-addr-l...end-addr-6 
Is the end address of the area to be displayed. 


Example 1 (COBOL): 


1 8 12 





CALL ‘SNAP’ USING DICE-CODES END-WS 
PIB END-PiB IMA END-IMA OMA END-OMA 


Example 2 (BAL): 


1 10 16 





ZG#CALL SNAP, (WSTAT1,WEND) 


ACTIVATION RECORD (SINGLE-THREAD IMS 90) 


PROGRAM INFORMATION BLOCK (PIB) (1) | 
THREAD CONTROL 


BLOCK (THCB) 





NOTES: 
G) Fixed-length area (3) Optional area 
(2) Contains 16-byte header in front of text (4) Used only by defined record management 


Figure 3—17. Single-Thread IMS 90 Activation Record Layout 
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ACTIVATION RECORD (MULTITHREAD IMS 90) THREAD CONTROL 


BLOCK (THCB) 
PROGRAM INFORMATION BLOCK (PIB) (1) 


OUTPUT MESSAGE AREA (OMA) (2) (3) 





CONTINUITY DATA AREA (CDA) (3) 


WORK AREA (WA) (3) 
INPUT MESSAGE AREA (IMA) (2) 


DEFINED RECORD AREA (DRA) (G3) (4) 


NOTES: 
Ca) Fixed-length area (G3) Optional area 
(2) Contains 16-byte header in front of text (4) Used only by defined record management 


Figure 3—18. Muttithread IMS 90 Activation Record Layout 


3.12.3. Edited Directory for Snapshot Dumps 


To obtain an edited directory for snapshot dumps, multithread IMS 90 users must indicate 
SNAPED=YES in the OPTIONS section of the configuration. The configurator then includes 
the module ZG#SNAPM in the input stream to the linkage editor in creating the IMS 90 
load module for online execution. If you omit the SNAPED parameter or indicate 
SNAPED=NO, the module ZGH#SNAPM is not included in the IMS 90 load module and 
snapshot dumps are printed without the edited directory. 


Single-thread IMS 90 users receive as a standard feature the edited directory on all 
snapshot dumps. Figure 3-19 illustrates a portion of a snapshot dump with an edited 
directory. If BASIC=YES is specified, the termination dump is not edited. 
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3.13. UTS 400 DOWNLINE LOAD CAPABILITY 


The Universal Terminal System 400 (UTS 400), in an IMS 90 communications 
environment, can perform certain functions in its own processor. The UTS 400 is 
particularly useful in editing and validating IMS 90 input messages, via user-written 
COBOL, MAC 80, or PLM programs. If any errors occur in input editing or validation, they 
can be handled directly at the UTS 400, without transmitting the message to the host 
computer. 


Your UTS 400 programs must be stored in the IMS 90 load library (the library containing 
your online IMS 90 load module and action programs) from where they are downline 
loaded to the UTS 400 at your direction during online processing. You have two ways of 
downline loading the UTS 400: 


= Enter the transaction code DLOAD to activate the IMS 90 downline load action 
program ZUKLOD (5.3.3). 


= Write your own downline load action program (3.13.1). 


Two types of UTS 400 loads may be accomplished: a load for an immediate execution that 
is loaded directly into the UTS 400 main storage, and a load to the UTS 400 auxiliary 
storage device (a cassette or a diskette). 


To use this downline loading feature, you must generate a resident ICAM and must specify 
DLLOAD=YES in the OPTIONS section of configurator input. 


The UTS 400 terminal accepting a downline load must be a master or primary UTS 400 
station, never a slave station. 


To use the downline loading feature, you should be familiar with the description of the 
UTS 400 terminal found in the fundamentals of ICAM user guide, UP-8194 (current 
version), and with the Universal Terminal System 400 programmer reference, UP-8359 
(current version). 


3.13.1. User-written Downline Load Action Programs 


As an alternative to using the ZUKLOD downline load action program, you can write your 
own downline load action program to read blocks of UTS 400 program code from the IMS 
90 load library to a UTS 400 terminal. The user-written downline load action program 
must contain the following: 


= # An 8-byte field defined for the UTS 400 load-module-name. The module-name must 
be moved into this field in the OMA that is being downline loaded before the 
SETLOAD function is called. 


=# One SETLOAD function call for each downline load is required. The SETLOAD 
function must be issued before any GETLOAD function call because initialization must 
occur before a block of code can be read from a UTS 400 load module. 
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GETLOAD function calls issued to read blocks of code from the UTS 400 load module 
into the data buffer in the OMA. 


A 400-byte area defined on the word boundary in the CONTINUITY-DATA-AREA. This 
area is used as a work area by the SETLOAD and GETLOAD function calls. 


The data-buffer and 2-byte field indicating SIZE defined in the GETLOAD function call. 
The data-buffer contains a block of code read from the load module. 


Before the GETLOAD function ts called, the size field should have the length of the 
buffer area in binary format. After the return from the GETLOAD call, the size field 
will have the number of bytes actually moved into the buffer area. This number will 
also be in the binary format. 


After the GETLOAD function call, the user downline load program must: 


Check for end-of-file (02) in the STATUS-CODE field of the PIB. 


Process the status code in the PIB for successful completion of the GETLOAD 
function call. 


lf the GETLOAD function is successful, the user downline load program should: 


Move ‘C’ to the AUX-FUNCTION field (the first byte of the AUXILIARY-DEVICE-ID field) 
of the output message header. 


Prefix the data block received from the GETLOAD function call with a proper heading 
to load this block either directly into the UTS 400 main storage or to an auxiliary 
storage device. This prefixed data block becomes the text in the downline load 
program's OMA whose length can be calculated using the length returned in the SIZE 
parameter of the GETLOAD function call. 


An example of the OMA and the prefixing operations required to format the text part 
of the OMA for immediate execution might look as follows: 


O01 OUTPUT-MESSAGE-AREA COPY OMA. 
O02 DOWNLINE-LOAD-MESSAGE. 

03 DOWNLINE-LOAD-HEADER PIC X(6). 

03 DOWNLINE-LOAD-TEXT PIC X(1000). 
The user downline load action program should move the 6-byte prefix, 
X'1BO0E30323130', into DOWNLINE-LOAD-HEADER to provide the header information 
for loading the UTS 400 main storage. 
lf the downline load is intended for the auxiliary storage device, the user action 


program should instead move X‘1313nnnnnnnn’ into DOWNLINE-LOAD-HEADER. 
Here ‘nnnnnnnn’ is a 4-character sequence naming the UTS 400 load program. 


~_ 


® 
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= Send the message from the user-written downline load action program OMA to the 
UTS 400 terminal using the continuous output feature. 


= Terminate the downline load action program with external succession (i.e., place ‘E’ in 
the TERMINATION-INDICATOR of the PIB) and name the downline load action 
program as the successor. The successor action program must then be prepared to 
handle a delivery notice in the form of an input message as described in 3.10.1.4. 
This includes testing the delivery notice for error and if an error occurs, moving an 
error message to the OMA before terminating the program normally (TERMINATION- 
INDICATOR=N in the PIB). 


lf the SETLOAD or GETLOAD function is unsuccessful and ERET=YES is included in the 
PROGRAM section of the configurator, the user downline load action program receives 
control with error indications set in the STATUS-CODE field of the PIB. For status code 
settings in this case, see status codes 3 and 4 in 3.13.1.1 and 3.13.1.2. The action 
program should then send an appropriate error message to the terminal. 


lf the SETLOAD or GETLOAD function is unsuccessful and ERET=YES is not configured, 
IMS 90 cancels the transaction and sends the following message to the terminal: 


DOWN LINE LOAD ERROR. 


lf the GETLOAD function returns an end-of-file condition (STATUS-CODE set to X‘0O2’ in 
the PIB), the buffer area will contain the transfer record. This is the last block that should 
be sent to the UTS 400; thus, no more GETLOAD functions should be issued for this load 
module. !f the blocks of code are sent to the main storage for the immediate execution of 
the program, then when the UTS 400 terminal receives a transfer record it automatically 
transmits a response (input message) indicating whether or not the downline load was 
successful. Therefore, the user-written downline load action program should not use 
continuous output to send this last block. It should follow the same procedure as for a 
successful GETLOAD function, except it should not move ‘C’ into the AUX-FUNCTION field 
of the output message header. 


The successor action program will then receive in its IMA the 24-byte message header from the 
UTS 400 in the following formats: 


-_$ i@—i—_ 24 bytes >| 


4 8 
DICE 


Successful load 


[A 24 bytes ooo 


4 8 
DICE 


Unsuccessful load 
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Table 3-21 defines the various error bit configurations (*) that can be returned in the last & 
byte of the message from the UTS 400. : 


Table 3—21. Rejected Load Error Byte Definition 


Error Type Probable Cause/Recovery 
a 


LOADFL contents (AA,.) prevents This vatue (AA,s) was not cleared by a UTS 400 
loading program which had been executed previously. 













The UTS400 operator should initiate a confidence 
test from the controller or master station and, 
upon completion of the test, the load should be retried. 

















Load addressed to a UTS 400 
slave station instead of a 
master station 


The load should be retried and addressed to 
the UTS master station. 














If main storage is available, the UTS 400 operator 
should assign the appropriate storage to the 
program. The load should be retried. If main storage 
is not available, the program should be 
recompiled, addressing available storage. 


Block overflowed available/ 
assigned main storage 









Start address of block is not 
in available/assigned main 
storage 


Addresses A and B not equal The OS/3 downline load procs should 
prevent this occurrence 


*Numbered from right to left; i.e. bit 7 is the most significant bit, bit O is the right-most or least significant bit. 





NOTE: 
It the user-written downline load action program is configured with ED/lT=tablename or 
ED/T=c tn tts ACTION section (or if the EDIT parameter is omitted), the DICE characters 
X‘10010707" are stripped from the message before it is sent to the action program. 
An example of the IMA might look as follows: 
O1 INPUT-MESSAGE-AREA COPY IMA. 
O02 UTS400-RESPONSE-MESSAGE. 
03 UTS400-RESPONSE-DICE PIC X(4). 


03 UTS400-RESPONSE PIC X(4). @ 


* - 
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The user-written downline load action program should: 


# Interrogate the response message and send an appropriate output message to the 
terminal indicating the success or failure of the downline load. 


= Terminate with normal termination; i.e., place ‘N’ in the TERMINATION-INDICATOR of 
the PIB. 


If the action program downline loads a program to a local storage device, the UTS 400 
terminal will not generate a response message after the last block of code is sent to the 
device. Therefore, the status of the downline load will not be known until the program is 
read from the local storage device into main storage. 


3.13.1.1. Downline Load Initialization 
The first function called by a downline load action program is the SETLOAD function: 


COBOL Format: 


CALL ‘SETLOAD’ USING uae 
work-area 


BAL Format: 


eae SETLOAD, (module-name,work-area) 
ZG#CALL 


where: 


module-name 
ls an 8-byte field containing the name of the UTS 400 program load module to be 
downline loaded. The UTS 400 program must be in the same load library as your 
action programs and the online IMS load module. 


work-area 
Is a 400-byte area defined in the CONTINUITY-DATA-AREA. This area must be 
word-aligned. | 


Status Codes Detailed Status Codes 

O O Successful SETLOAD 

3 | 1 Invalid request; invalid number of parameters 

: 7 Invalid request; function invalid for ne of request 

3 22 Invalid request; after the initial SETLOAD is issued, 


SETLOAD may not be issued again until the transfer 
record is received from the GETLOAD call. 


~ + 
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3.13.1.2. Downline Load Processing 


The GETLOAD function is called by the downline load program immediately after the 
SETLOAD function. it should be called repeatedly until end-of-file is reached for the UTS 
400 load module. 


COBOL Format: 


CALL ‘GETLOAD' USING\work-area 
buffer-area 
size 

BAL Format: 


ae Aone tami wr nnmariourninie einen 
ZG#CALL 


where: 


work-area 


Is the area previously defined in the SETLOAD function. 


buffer-area 
Is the data-buffer in the OMA where the user expects a block of code from his 
load module. 


size 
ls a 2-byte field where the length (size) of the buffer-area is stored. 


Status Codes Detailed Status Codes 
O 0 Successful GETLOAD 
2 0 End-of-load module (transfer record received). Note that 


end-of-file is set at the time the last block of data 
(transfer record) is passed to the action program. 


3 20 Invalid request; work-area address invalid or SETLOAD 
was not issued before GETLOAD. 

3 21 Invalid request; data buffer too small (less than 10 bytes). 

4 XX [/O error. XX is the error code (in binary) returned by the 


OS/3 loader. Note that these error codes are explained in 
the system messages programmer/operator reference, 
UP-8076. 


® - 


UP-8614 Rev. 1 SPERRY UNIVAC O0S/3 3-111 
IMS 90 APPLICATIONS Update B 


3.14. SCREEN FORMATTING SERVICES 


Screen formatting services is a method of displaying predefined formatted screens at a 
terminal. These predefined screens simplify the action programmer's output formatting job 
and can also aid the terminal operator in his data entry procedure. IMS 90 places the 
predefined screen formats in your action programs via CALL functions in BAL and COBOL 
programs or via output format specifications in RPG Il programs. You can display screen 
formats on the following devices: 


= UNISCOPE 100 (must have protection feature) 
2 UNISCOPE 200 (must have protection feature) 


=» UTS 400 (if operating in native mode, must have PROTECT/FCC switch set to FCC 
and control page set to XMIT VAR) 


a UTS 20 
B Workstations 


You indicate use of screen format services by including the SFS parameter in the 
OPTIONS section of your IMS 90 configuration. (See IMS system support functions user 
guide/programmer reference, UP-8364 (current version).) 


You predefine your screen formats offline from IMS 90 via the OS/3 screen format 
generator. (Refer to screen format services concepts and facilities user guide/programmer 
reference, UP-8802 (current version).) In your screen format description, you assign a 
format name to each screen format and the screen format generator (SFG) places it in the 
format library SYSFMT. SYSFMT is a MIRAM disk file where all the screen formats used by 
your action program reside. Only one screen format file is supported per execution of IMS 
90. 


When you use screen formats, your IMS 90 job control stream must include a device 
assignment set for each device type using screen formatting. These device assignments 
define where the formats used by your action programs reside. You must use an LFD 
name of TCO1FMITF for the first terminal class, TCO2ZFMTF for the second, etc. In addition, 
this job control stream must include a //OPTION OFT=+n statement, where n specifies 
the number of device types. This number should agree with the number specified on the 
SFS configurator parameter. (See the IMS system support functions user 
guide/programmer reference, UP-8364 (current version).) 


Note that action programs using screen formatting services may not run in a batch (online 
or offline) environment; however, the IMS screen format services interface supports the 
writing of formatted screens to auxiliary devices on applicable terminals. 


You must put the AUX-DEVICE-NO field and AUXILIARY-FUNCTION field in the output 
message area header before building the screen format. You cannot specify the AUX- 
DEVICE-NO field with an error screen because it causes unpredictable output on the 
auxiliary device. 


Table 3-22 illustrates screen format services support of auxiliary devices. 


—<— 


’ 
* 
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Table 3—22. Screen Format Services Support of Auxiliary Devices 


Input/Output Options Contents piace Auxiliary Devices 
Inhibit | Continuous |No ca UTS 400 UNISCOPE 100/200 


Suppression Space 
Ke td b Supported Not Supported Supported Not Supported 


Suppression Hex 
F3 3 
aa mended\O® Heemnened@ 










Print Mode 


cageie ble 
output at screen 
and auxthary 
device} 


| | “| 


Print 
Transparent 


X 

(unpredictable 
output at screen 
and auxiliary 
device) 





Print Form 
(ESC H) 


ci 
X 
(recommended) 
or 
| fee oe foe] 
Variable 
i CC 


Transfer y C5 E D5 X (field control 
Changed characters not 
(ESC &) Supported) 


Transfer 
All 
(ESCG) 


Transfer 


o< 

~ 
8 

— 
oe 


ve 


©) 








X E8 Y FR X (field control 
characters not 
Supported) 


printer - same format as screen 


Legend: 


printer — same information as screen; no carriage returns 
cassette/diskette - same format as screen; no field control characters 
cassette/diskette - same format as screen; only records unprotected fields 


cassette/diskette — same format as screen; records all fields and all field control characters 


O@QOe®oOHO 


cassette/diskette -— not available 
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3.14.1. How IMS 90 Handles Screen Formatted Messages 


‘When your action program requests a screen format, IMS 90 retrieves the screen format 
you name and places it in an action program-specified buffer (usually the output message 


area (QMA)). You must reserve the first 16 bytes of your buffer area for an output 
message header. 


The screen format coordinator places the output display constants of the format into their 
respective locations within the screen buffer. These constants are always protected. IMS 
90 inserts into the format buffer the variable data you supply in your action program. 
Variable data is all the data to be displayed on the terminal except the display constants. 
Figure 3-19A shows an output screen containing display constants and variable data. 












EMPLOYEE NUMBER: {12345678 
NAME: JOHN DOE 


ADDRESS: 123 OAK ST. 
ALLENTOWN, PENNA. 
987654 


DISPLAY g— | 
CONSTANTS 


















VARIABLE DATA 


Figure 3—19A. Output Screen Format with Display Constants and Variable Data 


Any field you define as input or both input and output in your action program is an 
unprotected field. This means that the terminal operator is free to change that field when 
making data entries on the screen format. When building your screen buffer, if you define 
a variable data field as output only, it is protected. Figure 3-19B shows an input screen 
containing the input fields (address) that the terminal operator has changed. 









EMPLOYEE NUMBER: 12345678 
NAME: JOHN DOE 


ADDRESS: §753 PINE ST. 
PHILADELPHIA, PENNA. 
191983 


DISPLAY 
CONSTANTS ~ 









CHANGED INPUT FIELDS 


Figure 3—19B. Input Screen Format with Display Constants and Changed Input Fields 


When your action program terminates with delayed internal succession or continuous 
output, IMS 90 forces the format to be output only. Also, you must use an output only 
format for any formatted output message being switched to a terminal other than the 
source terminal. A message wait light entered to retrieve a switched message cancels any 
screen format currently effective at the terminal. Also, function keys passed to the action 
program cancel any screen format currently effective at the terminal. Your action program 
may send multiple formatted messages to the originating terminal; however, only the last 
format may be used for the subsequent input format. 





* a 


UP-8614 Rev. 1 SPERRY UNIVAC 0S/3 3-113 


IMS 90 APPLICATIONS Update B 





When the terminal operator fills in input data on the screen format, the data entered is 
validated before IMS 90 passes control to your action program. IMS 90 first checks the 
message for terminal command input before requesting the screen format coordinator to 
validate the input message. If the input message contains a terminal command other than 
ZZRSD, IMS 90 processes it accordingly and cancels any screen format currently effective 
at the terminal. ZZRSD causes the last output message to be resent, thus retaining the 
Current screen format. 


To schedule an action program to receive the formatted input data, you must terminate the 
CALL BUILD action program with external succession (E). If you terminate the CALL BUILD 
action program with normal succession, the first input field must contain a valid 
transaction code. 


If an input message contains a transaction code, in the first five bytes, IMS 90 verifies the 
code and if it is invalid, sends the input message back to the terminal and causes the 
transaction code to blink. This action does not cancel the effective screen format. 


When the input message does nt contain a terminal command or invalid transaction code 
message, IMS 90 requests the format coordinator to validate the message. If the input 
data filled in by the terminal operator is valid, IMS 90 places only that data into your 
Successor action program’s IMA. IMS 90 does not perform any other editing (simple 
editing or expanded input editing) on this input even if configured for the related action. 
Your action program can continue processing, possibly writing the new input to a data file. 
lf there are input errors, IMS 90 allows the terminal operator to correct the inputuntil the 
retry count specified at screen format generation time is exhausted. (See screen 
formatting concepts and facilities user guide/programmer reference, UP-8802.) 


Once the retry count is exhausted, the successor action program receives control. At that 
time, the PIB contains a status code of 7 and a detailed status code of 0. (See 3.14.2.1.) 


NOTE: 


lf you want to terminate with normal succession after you output an input/output screen 
format, you must enter a valid transaction code tn the first input field. 


3.14.2. Processing Screen Formatted Messages with COBOL and BAL 
Action Programs 


When you are ready to display a screen format on a terminal, your action program must 
first move the destination terminal-id into the first 4 bytes of the output message header 
and the output area length into the text length field of the output message header before 
issuing a BUILD function call statement. The output area length must be large enough to 
hold the format constructed by the screen format coordinator. To determine this value, see 
the formula described on the OUTSIZE parameter of the configurator ACTION Section in 
the system support functions user guide/programmer reference, UP-8364 (current 
version). 


IMS 90 passes the format name you supply on the BUILD function to the screen format 
coordinator, which retrieves that screen format from the format file (SYSFMT). IMS 90 
then places the screen format into the output area supplied by your action program. Your 
action program may add variable data to the screen format by supplying additional 





a a 
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parameters on the CALL BUILD function. Issuing a CALL RETURN or CALL SEND then 
sends that screen message to the terminal. The terminal operator then enters data that ts 
verified and stored in your successor action program's input message area (IMA). Your 
successor action program may do further validation before processing the input data. 
Figure 3-20 illustrates message processing using the screen format services. 


NOTE: 


The LOW-VALUES figurative in COBOL is not valid output data for variable output fields in 
a CALL BUILD function. It translates to binary zeros. The HIGH-VALUES figurative 
constant. however, causes an input field to blink in a CALL REBUILD function because it 
translates to binary ones. 





0S$/3 
SCREEN 
FORMAT . IMS 90 
COORDINATOR 
CALL BUILD 
USER USER 
ACTION ACTION 
PROGRAM (A) PROGRAM (B) 
SCREEN 
FORMAT 
FILE 
OMA IMA 





CALL RETURN/SEND 










ENTER ea IMS 90 STORES 
INPUT DATA "ADDR: 12 BROWN ST, ONLY INPUT 
INTO SCREEN DATA ENTRIES iN 
FORMAT IMA 


Figure 3—20. Processing Screen Formatted Messages with COBOL or BAL Action Programs 
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lf you include a variable data area on the BUILD function, you may also include an output- 

status area large enough to hold one status byte for each variable data field. The screen 

format coordinator uses this area, when specified, to fill in error codes when it finds errors 

in the output validation of the variable data. When a validation error occurs, the screen 

format coordinator places X‘FF’ in the error field in your variable data area and one of the 
following field status error codes into the status byte for the invalid field. 


Output Validation 


Error Codes Cause of Error 

O1 Nonnumeric keyin to a numeric field or subfield 

O2 Nonalphabetic keyin to an alphabetic field or subfield 
O05 Range check failure | 

O06 Field not in packed decimal format 


After your action program issues the BUILD function, the program information block (PIB) 
Status and detailed status code fields reflect the status of the BUILD function. (See 
3.14.2.1 for status code explanations.) A status code of zero means the function call was 
successful and no output validation errors occurred; therefore, the format area (OMA) will 
contain a constructed output screen buffer. 


Once the action program has issued the BUILD function, do not change the contents of the 
output message area that contains the output header, screen format, and variable data. 
Modification of this output message area may cause unpredictable results since: 


=» The information contained in the output header is used by screen format services to 
construct an appropriate screen format. 


= Screen format services rely on the format structure being the same when received at 
input time as it was when presented to the action program at BUILD function time. 


om r 
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To send the screen buffer contents (i.e., format and optional variable data) to the terminal, your 
action program issues a SEND or RETURN function. If this screen buffer terminal display 
contains at least one fill-in field for data input (i.e., the format is input or input/output), this 
screen format remains in effect at the terminal until the following input. If, however, you are not 
expecting input from the formatted screen, i.e., the terminal operator clears the screen before 
entering the next input message, you must clear the SFS-OPTIONS field in the COBOL output 
message header or the ZAHOSFSO field in the BAL output message header. Use the following 
Statement in COBOL to clear the SFS-OPTIONS field: 


MOVE LOW-VALUES TO SFS-OPTIONS. 
In basic assembly language, the following statement does the same thing: 


l 10 16 72 





MV I ZA#0SFSO,X‘00’ 
(See Figures 3-10 and 3-11.) 


Suppose the terminal operator wants to enter data from the terminal. If the data he enters 
is valid, that data is placed in the successor action program’s IMA. lf he enters invalid 
data, however, he is allowed to correct his entry until the retry count specified at screen 
format generation time is exhausted. In this case, IMS 90 automatically blinks the invalid 
field entered at the terminal. 


Once the retry count has been exhausted, IMS 90 schedules your successor action 
program whose IMA contains the input data entered from the terminal. The input data is 
followed by one status byte for each input field, indicating that the field is valid. When an 
input validation error is detected, one of the following field status error codes is entered in 
the status byte for the invalid field in your successor action program’s IMA: 


Input Validation 


Error Codes Cause of Error 
01 Nonnumeric keyin to a numeric field or subfield 
O2 Nonalphabetic keyin to an alphabetic field or subfield 
O03 Correct number of characters not entered 
04 Decimal point alignment error 


O05 Range check failure 
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In addition, the screen format coordinator places hexadecimal F’s into the invalid data 
fields in your IMA. Note that the length field in the input message header indicates only 
the length of the input data items and does not include their status bytes. Once IMS 90 
has indicated invalid fields, you may want to send a general error message to the terminal | 
operator and terminate the transaction. 


Your action program can validate input data on a more detailed level than the screen 
format coordinator. When the terminal operator enters input data that your program 
determines is valid, you can issue the REBUILD function to construct an error screen 
format. Before you issue a REBUILD function call, however, your program must place the 
output area length into the output message header and replace invalid input data with 
hexadecimal F's. 


When you issue the REBUILD function, the screen format coordinator replaces any fields 
containing hexadecimal F’s with the appropriate blink characters as it constructs the error 
screen format in the OMA. Finally, when your action program issues a subsequent 
RETURN or SEND function, the field in error blinks on the screen format at the terminal 
and all other fields remain unchanged. 


In summary, your BAL or COBOL action program issues two function calls to send a 


formatted output message to the terminal. The BUILD and the SEND/RETURN functions 
construct the screen buffer contents and transmit them to the terminal. 


SEND/RETURN | @ 


ACTION 


PROGRAM 





The REBUILD and SEND/RETURN functions reconstruct erroneous screen buffer contents 
for transmission to the terminal. 


SEND/RETURN 


ACTION 


PROGRAM 








UP-8614 Rev. 1 SPERRY UNIVAC OS/3 3-116a 
IMS 90 APPLICATIONS Update A 


3.14.2.1. Building a Screen Buffer (BUILD) 


Your action program must issue a BUILD function call to construct a screen buffer in your 
action program's OMA. On return, the screen buffer always contains the display constants 
placed there by the screen format coordinator and may optionally contain variable data 
merged with the screen format. The format of the BUILD function call follows: 


COBOL Format: 


CALL ‘BUILD’ USING buffer-address format-name 
[variable-data data-size [output-status]]. 


BAL Format: 


i BUILD, / buffer-address, format-name[variable-data,data-size - 
ZG#CALL [,output-status]] 


where: 


buffer-address 
Is the address of an output area (usually the OMA) into which the constructed 
screen is placed. This area must be full-word aligned and begin with a 16-byte 
output message header with the destination terminal-id and output area length 
fields set as indicated on the OUTSIZE parameter. (See 3.14.2.) 


format-name 


Is the address of an area containing the 8-byte format name that identifies the 
desired format. 


vartiable-data 

Is the address of an area containing a string of variable data to be merged with 
called format. When this parameter is not specified, only the screen format 
constants are sent to the terminal as an aid to the operator entering input data. If 
you use this paramter and do not describe output fields in your action program 
(this is an input-only format), the variable-data parameter is invalid and IMS 90 
returns an error status in the PIB. There are no default values that can be 
generated by the screen format generator for output fields that can be used at 
CALL BUILD function time. Therefore, you must supply variable data for all of the 
output fields. 


lf you want to have default values for some or all of your input fields, generate 
the fields as being both input and output fields, and supply output in the variable 
output data area at CALL BUILD function time. 


data-size 
ls the address of a half word containing the length of the variable data area. This 
parameter is required if you specify a variable data area. 
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@ output-status 
Is the address of the area into which the screen format coordinator places status 


errors found in the output validation of variable data. This parameter is valid only 
if the variable-data parameter is used. If omitted, output validation is not 


performed. 


lf the BUILD function call is unsuccessful, no screen buffer is constructed and IMS 90 
sends one of the following status and detailed status codes to the PIB of your action 


program. 


Status 
Code 


1 


3 


Detailed 


Status Code Reason for Error 


12 


Supplied format name could not be found 
Incorrect number of parameters 


Invalid parameter value (e.g., an address not within action 
program's activation record) 


SFS not configured 

Invalid terminal name 

Validation error; all error fields within variable data area are 
replaced by hexadecimal F’s and affected field error statuses 
are set in the output-status area. 

Format area (output buffer) not large enough* 

Variable data area not large enough 

insufficient number of terminal classes 

Variable data specified for input format 


Format width greater than screen width 


Fatal error (e.g., |1/O error) 


3.14.2.2. Creating an Error Formatted Screen (REBUILD) 


You use the REBUILD function to construct an error screen format. The REBUILD function 
is used more effectively when your action program needs to provide more detailed input 
data validation than the screen format coordinator provides via the input validation error 
codes to the IMA (3.14.2). The format of the REBUILD function call follows: 


*When IMS 90 returns this error status, the length field in the output message header portion of your format area will 
contain the actual length required for this format. 
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COBOL Format: 


CALL ‘REBUILD’ USING buffer-address variable-data. 


BAL Format: 


CALL REBUILD, (buffer-address, variable-data) 
ZG#CALL 


where: 


buffer-address 
Is the address of an output area (usually the OMA) into which the constructed 
screen is placed. This area must be full-word aligned and begin with a 16-byte 
output message header as specified for the CALL BUILD function. 


variable-data 
Is the address of an area containing a string of fields including error fields into 
which the screen format coordinator or action program has placed hexadecimal 
F’s. This is usually part of the IMA and contains all of the input data keyed in by 
the terminal operator. 


Before issuing a REBUILD function call to construct the error screen format, you must 
place the output area length in the output message area. In addition, your program must 
replace invalid input data fields with hexadecimal F's in the IMA. 


When you tssue the REBUILD function call, the screen coordinator replaces erroneous 
input data fields (hexadecimal F’s) with blink characters and constructs an error screen 
format in the OMA. A subsequent RETURN or SEND function call sends the error screen 
format to the terminal operator indicating the fields that need correction. 


If the REBUILD function call is unsuccessful, no error format is constructed and IMS 90 
sends one of the following status and detailed status codes to the PIB of your action 
program: 


Status Detailed 
Code Status Code Reason for Error 





1 ~ Supplied format name could not be found 
7 1 Format area not large enough 

7 5 Format width greater than screen width 
7 6 Fatal error (e.g., |1/O error) 

7 7 Rebuild not allowed 

7 8 Invalid field 


7 9 No error field detected 
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3.14.3. Processing Screen Formatted Messages in RPG Ii Action Programs 


To use screen formatting services in your RPG Il action program, you follow the same 
procedure in coding the control card and file description specification forms as you do for 
any other RPG Il action program.) For example, code the letter A in column 74 of the 
control card specifications to designate an action program and identify the program as 
usual in columns 75 through 80. On the file description specification you name and 
describe the user and IMS 90 files. The input format specifications describe the IMS 90 
IMA file and user variable record fields associated with terminal input to a successor 
action program. When you enter data from the terminal and pass it to a successor action 
program, you must describe these input fields on the input format specifications. The 
calculation specifications retrieve the user record for inclusion in the screen format buffer 
(your action program’s OMA). Finally, the output format specifications name the screen 
formats your action program uses and any variable data required by the screen format. 
Only one screen format is allowed for each output record. You identify the screen format 
on the first field description for each output record and follow it with the description of any 
variable data required by each named screen format. 


Although RPG Il action programs normally do not use a work area, when you use screen 
formats you must specify a WORKSIZE keyword parameter in the ACTION section of the 
configuration equal to the size of the variable output data. 


When the terminal operator keys in the transaction code for your action program, IMS 90 
loads your RPG II action program, which moves variable data to the OMA. (You must allow 

© 16 bytes in the OMA for the header that immediately precedes the variable output data.) 
Subsequently, IMS 90 transmits the entire screen format including your variable data to 
the terminal. 


The terminal operator may then enter data, which ts verified and stored in your successor 
action program’s input message area (IMA). Figure 3-20A illustrates the processing of 
screen formatted messages for RPG Il action programs. 


Once your action program builds the screen format, do not change the contents of the 
output message area that contains the output header, screen format, and variable data. 
Modification of this output message area may cause unpredictable results since: 


= Screen format services uses the information contained in the output header to 
construct an appropriate screen format. 


= Screen format services relies on the format structure being the same when received 
at input time as it was when presented to the action program. 


If IMS 90 cannot build the screen buffer, it sends one of the following status and detailed 
Status codes to the PIB of your action program, which you can examine when you get a 
snap dump. 


Status Detailed 
S$ Code Status Code Reason for Error 


1 - Supplied format name could not be found 


3 12 SFS not configured 
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Status Detailed @ 
Code Status Code Reason for Error 
6 4 Invalid terminal name 
7 O Validation error; all error fields within variable data area are 


replaced by hexadecimal! F's. 


7 1 Format area (output buffer) not large enough 
7 2 Variable data area not large enough 

7 3 Insufficient number of terminal classes 

7 4 Variable data specified for input format 

7 5 Format width greater than screen width 

7 6 Fatal error (e.g., |/O error) 
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Figure 3—20A. Processing Screen Formatted Messages with RPG Il Action Programs 





Figure 3-20B shows a sample snap dump for an RPG II action program that requested an 
invalid screen format name. The first 2 bytes of the PIB indicate a status code of 014g, i.e., 
supplied format name was not found. 
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Figure 3—20B. Snapshot Dump with PIB Status Code Of (Screen Format Not Found) 
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You can construct an error screen format to notify the terminal operator when a user 
record cannot be found. To do this, you define your error screen display constants at 
screen format generation time and indicate the name of the error screen format and any 
variable fields on your output specifications format. For a good example of what is 
generated on an error screen, see Figure 3-39E. 


3.15. SAMPLE COBOL ACTION PROGRAMS 


Four transactions using COBOL action programs are described in 3.14.1 through 3.14.4 
and Figures 3-21 through 3-30. Program DISP (Figure 3-22) illustrates the use of 
previously coded DICE sequences stored in a COPY library. The DICE sequence coding is 
shown in Figure 3-23. Programs ACT1 and ACT2 (Figures 3-27 and 3-28) illustrate a 
dialog transaction, with ACT1 naming ACT2 as external successor. Figures 3-29 and 3-30 
illustrate the use of the continuous Output option. PRINT (Figure 3-29) creates continuous 
output to be printed at the originating terminal and uses delivery notice scheduling for 
control and recovery. BEGIN1 (Figure 3-30) provides an example of initiating a print 
transaction via the SEND function to perform continuous output at a different terminal 
from the one originating the processing: it uses output-for-input queueing. These two 
programs are not complementary; the print transaction initiated by BEGIN1 is not 
described, but it would necessarily be quite different in design from PRINT. 


3.15.1. Sample COBOL Program Using Previously Coded DICE Sequences 


The sample COBOL program in Figure 3-22 retrieves a record from the customer file 
(CUSTFIL) and displays it at the terminal. The program is called by the transaction code 
DISP, which also is the name of the program, and the 5-digit numeric key of the record 
desired. Figure 3-21 shows a sample input message and the corresponding output display. 


DISP 91234 
CODE CUSTOMER NAME ADDRESS CITY-STATE 


81234 JOHN DOE 1212 JACKSON PHILA.,PA 
BALANCE-DUE PAYMENT-DUE YR-TO-DATE VOL 
358.22 58.89 1,965.38 





Figure 3—21. Sample Transaction Displaying Customer Record 
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In case of an invalid record key in the input message, or any error condition detected by 
IMS 90, the program moves an error message to the output message area and terminates 
the transaction. 


Note that the action program DISP uses DICE, previously coded and filed in a copy library, 
for homing the cursor, clearing the screen, and repositioning the cursor to a new line. 
Figure 3-23 presents an example of the coding by which the appropriate DICE sequences 
might be prepared for entry into a specified copy library, where they would be available for 
use in an action program referencing them as DISP does (via the first 01 level COPY 
statement in tts working-storage section). 


1 8 12 


IDENTIFICATION DIVISION. 
PROGRAM-ID. DISP. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. UNIVAC-9030. 
OBJECT-COMPUTER. UNIVAC-9030. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 = CUSTFIL PIC X(7) VALUE ‘CUSTFIL’. 
77 =TEXT-1 PIC X(32) VALUE ‘PROCESSING ERROR,STATUS CODE = '. 
77 = TEXT-2 PIC X(23) VALUE ‘DETAILED STATUS CODE = ' 
01 DICE COPY DICE. 
01 CUSHODR1. 
02 CUSHD! PIC A(6) VALUE ‘ CODE ’. 
02 CUSHD2 PIC A(20) VALUE ‘CUSTOMER NAME 
02 CUSHD3 PIC A(15) VALUE ‘ADDRESS 
02 CUSHD4 PIC A(15) VALUE ‘CITY-STATE 
02 CUSHDS PIC A(5) VALUE ‘ZIP 


01 CUSHDR2. 
02 CUSHDE PIC A(15) VALUE ' BALANCE -DUE 
02 CUSHD? PiC A(15) VALUE ‘ PAYMENT-DUE 


02 CUSHD8 PIC A(15) VALUE * YR-TO-DATE VOL’. 
LINKAGE SECTION. 
01 PROGRAM-INFORMATION-BLOCK COPY PIB. 
Ol INPUT-MESSAGE-AREA COPY IMA. 
02 TRANSAC-CDE PIC X(4). 
02 FILLER PIC X. 
02 REC-KEY PIC X(5). 
02 REC-NO REDEFINES REC-KEY PIC 9(5). 
01 WORK-AREA. 
02 CUS-REC. 


03 CDE PIC X(5). 
03 NAME PIC X(20). 
03. ADDR PIC X(15). 
03 CTY-STE PIC X(15). 
03 ZIP PIC 9(5). 
03 BLNCE-DUE PIC $9(9)V99 COMP-3. 
03 DUE-IN PIC $9(9)V99 COMP-3. 
03 YTD-VOL PIC 9(6)V99. 
02 ERROR-MSGE. 
03 TXT-1 PIC X(32). 
03 STAT PIC 9(4). | 
03 TXT-2 PIC X(23). 
03 DSTAT PIC 9(4). 


Figure 3—22. Sample COBOL Action Program DISP (Part 1 of 2) 
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8 12 
01 QOUTPUT-MESSAGE-AREA COPY OMA. 

02 LINE-0O PIC X(4). 

02 LINE-1 PIC X(64). 

02 CR-1 — PIC X(4). 

02 \LINE-2. 
03 CDE PIC X(5). 
03 FILLER PIC X. 
03 NAME PIC X(20). 
03 ADDR PIC X(15). 
03 CTY-STE PIC X(15). 
03 ZIP PIC X(5). 

02 CR-2 PIC X(4). 

02 LINE-3 PIC X(45). 

02. CR-3 PIC X(4). 

02 LINE-4. 
03 FILLER PIC X. 
03 OUT-BAL PIC 222,222 ,229.99. 
03 FILLER PIC X(5). : 
03 OUT-DUE PIC 222,222 ,222.99. 
03 FILLER PIC X(5). 
03 OUT-VOL PIC 222,272.99. 

02 CR-4 PIC X(4). 

02 LINE-13 PIC X(4). 


PROCEDURE DIVISION USING PROGRAM-INFORMATION-BLOCK 


INPUT-MESSAGE-AREA WORK-AREA OUTPUT -MESSAGE-AREA. 


STRT-CDE-SECT. 
MOVE CURS-COORD TO LINE-0 
MOVE CURS-HME TO LINE-13. 
MOVE CR TO CR-1, CR-2, CR-3, CR-4. 
CUSTOMR-FILE-SECT. 
ENTER LINKAGE. 
CALL ‘GET’ USING CUSTFIL CUS-REC REC-KEY. 
ENTER COBOL. 
IF STATUS-CODE IS NOT = 0 GO TO PROCESS-ERROR. 
MOVE CUSHDR1 TO LINE-1. | 
MOVE CORR CUS-REC TO LINE-2. 
MOVE CUSHDR2 TO LINE-3. 
MOVE BLNCE-DUE TO OUT-BAL. 
MOVE DUE-IN TO OUT-DUE. 
MOVE YTD-VOL TO OUT-VOL. 
GO TO NORMAL-TERM. 
PROCESS-ERROR. 
MOVE TEXT-1 TO TXT-1. 
MOVE STATUS-CODE TO STAT. 
MOVE TEXT-2 TO TXT-2. | 
MOVE DETAILED-STATUS-CODE TO DSTAT. 
MOVE ERROR-MSGE TO LINE-1. 
MOVE REC-KEY TO ADDR OF LINE-2. 
NORMAL-TERM. 
ENTER LINKAGE. 
CALL ‘RETURN’. 
ENTER COBOL. 


Figure 3—22. Sample COBOL Action Program DISP (Part 2 of 2) 
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01 DICE COPY DICE. 
: DICE SPECIAL CHARACTERS FOR PROGRAM DISP. 


* FORMS CONTROL & CLEAR. CURSOR TO ROW Y, COLUMN X, AND CLEAR 
: SCREEN. X°10030201' 
. MULTEPUNCHES 12-11-9-8-1, 12-9-3, 12-9-2, 12-9-1. 


02 CURS-COORD. 


03 DICE-1 PiC X(2) VALUE 
03 ROW-Y1 PIC X(1) VALUE 
03 COL-X1 PIC X(1} VALUE 
. POSITION CONTROL NEW LINE. X‘'10040000'. 


° MULTIPUNCHES 12-11-9-8-1, 12-9-4, 12-0-9-8-1, 12-0-9-8-1. 
77 CR PiC X(4) VALUE 


. SET COORD-CURSOR TO HOME. X‘10010000'. 
‘ MULTIPUNCHES 12-11-9-8-1, 12-9-1, 12-0-9-8-1, 12-0-9-8-1. 


77 ~=CURS - HME PIC X(4) VALUE 


: POSITION CONTROL & CLEAR- CLEAR TO END OF LINE & NEW LINE. 
% X'10050000'. 
° MULTIPUNCHES 12-11-9-8-1, 12-9-5, 12-0-9-8-1, 12-0-9-8-1. 


77 CLR-LINE PIC X(4) VALUE © 


: APPENDING CODE FOR UNFSCOPE-100 COP. X‘12° 
. MULT EPUNCH 11-9-2. 


7? OC PIC X(1) VALUE ° 


° START OF ENTRY CHARACTER SOE. X'IE’ 
MULTEPUNCH 11-9-8-6. 


77 SOE PIC X(1) VALUE 


Figure 3—23. Example of DICE Sequences Filed in a COPY Library 


3.15.2. Sample COBOL Programs Performing Dialog Transaction 


The two action programs ACT1 and ACT2 (Figures 3-27 and 3-28) perform a dialog inquiry 
transaction. The initial input message and various possibile input and output messages of 
the dialog transaction are shown in Figures 3~24, 3-25, and 3-26. Use of the UNISCOPE 
100 display terminal is assumed. This transaction references two indexed files named 
STATE and CITY. The STATE file contains a record for each state. In each record is the 
state name, state population, and the name of the capital city. The CITY file contains a 
record for each city. In each record is the city name, city population, and state name. City 
names in the CITY file are assumed to be unique for the purposes of this example. 
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The transaction is designed to provide information about a state. The operator enters the 
name of a state. In response, the state name, population, and capital name are given. 
Either the population of the capital city or termination of the transaction can then be 
requested. 


The input message (line 0) is the same for Figures 3-24, 3-25, and 3-26. S is a 
transaction code that uniquely identifies the state transaction to IMS 90. The S is followed 
by a single place to delimit it from the remaining text of the message. The name of a state 
is entered then and the message is transmitted to IMS 90. The symbol “lis the cursor and 
is supplied by the hardware. 


IMS 90 associates the transaction code S$ with the action program ACT1. This relationship 
is established at IMS 90 configuration time. When ACT1 is initiated by action scheduling, 
the input message text is in the input message area (IMA) which is described in the 
linkage section. This area consists of a control header and a text area. The description of 
the control header is copied from the IMS 90 copy library; the descriptions of the output 
message area (OMA) control header, and the program information block (PIB) also are 
copied. 


ACT1 uses the name of the state given in the input message to obtain a record from the 
STATE file. If the record exists, the name of the state, state population, and capital name 
are placed in the OMA. The output message headings and control characters are moved to 
the OMA from the working-storage section. 


ACT1 saves the name of the capital city in the continuity data area. The contents of this 
area are automatically passed to the succeeding action program, ACT2 by IMS 90. ACT1 
designates ACT2 as its external successor. The termination code E, for external 
succession, is moved to the TERMINATION-INDICATOR field in the PIB. The identification 
of the program, ACT2, is moved to the SUCCESSOR-I!D field of the PIB. ACT1 terminates 
by means of a CALL ‘RETURN’ statement. 


The output message built by ACT1 in its OMA is sent to the originating terminal by IMS 
90 after ACT1 is terminated (lines 1-5 in Figure 3-24). 


S ALASKA 
STATE STATE-POP CAPITAL 


ALASKA 226,098 JUNEAU 


CAPITAL-POP? >NO YES 


—“ OD on tm & AO = & 


7,888 





NOTE: 


The cursor (7} may appear at only one location on the screen at any one time. In this example, it also would have 
_ appeared after ALASKA when the operator entered the initial input message {line 0) and after NO upon 
transmission of the first output response built by ACT 1 (line 5). The start-of-entry character (>) may appear at 
multiple focaiions. 


Figure 3—24. Sample Dialog Transaction with Option Taken 
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9 S ALASKA 

; STATE STATE-POP CAPITAL 

3 ALASKA 266,008 JUNEAU 

4 

5 CAPITAL-POP? NO YES 
6 TRANSACTION COMPLETE 

Figure 3—25. Sample Dialog Transaction with Option Not Taken 

i] S ALASKA 

] ERROR -STATE NAME [INVALID 1 





Figure 3—26. Sample Dialog Transaction with Error Message 


The output message (line 5, Figure 3-24) gives the terminal operator the option to request 
the population for the capital city of the state or to terminate the transaction. The start-of- 
entry and cursor characters are positioned in the output message so that: 


1. If the operator wants to terminate the transaction without seeing the capital 
population, he only needs to press TRANSMIT. 


2. If the operator wants to see the capital population, he must press TAB and then 
~ TRANSMIT. 


The option on line 5 in Figure 3-24 is the second input message, which always results in 
the scheduling of ACT2 (Figure 3-26). When the YES option is selected by the terminal 
operator, ACT2 obtains the CITY record for the capital city named in the continuity data 
area, builds an output message containing the capital population (line 7, Figure 3-24) and 
then terminates normally. 


Lines O through 5 in Figure 3-25 are the same as lines O through 5 in Figure 3-24; 
however, the response to the option is different. The NO option is selected, and ACT2 
moves zero to the TEXT-LENGTH field in the output message area control header before 
coming to a normal termination. Since no output message text is provided by ACT2, IMS 
90 returns a standard transaction termination message to the originating terminal, as 
shown in line 6 in Figure 3-25. 


In Figure 3-26, line O remains the same as it was in Figures 3-24 and 3-25. However, in 
the example, no such record can be found and the state name is assumed to be invalid. 
An error message is built in the output message area. The text length of the error 
message is moved to the TEXT-LENGTH field of the output message area control header to 
override the prespecified text length. The transaction terminates with a CALL ‘RETURN’ 
statement. The contents of the output message area are sent by IMS 90 to the originating 
terminal, as shown on line 1 in Figure 3-26. 
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IDENTIFICATION DIVISION, 

PROGRAM-1D. ACT4. 

ENVIRONPIENT OIVISTION. 

CONFIGURATION SECTION. 

SUURCVE-COMPUTER. UNIVAC-OS3. 

OBJECT-COMPUTER. UNIVAC-U05S3. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

77 STATE PIC AC7) VALUE ‘STATE’. 

77 ERROR-TEXT-LENGTH PIC 904) COHP-4 VALUE 34. 


O4 LINE-O. 
O2 DLE Fic xX VALUE =’ 40’. 
Of FCAC PIC xX VALUE =’0O5". 
O2 ROUW-O PIC xX VALUE =°60’, 
O02 COLUNK-O PIC X VALUE =’00’. 
04 LINE-i-NSG-48 PIC X(39) VALUE ‘’STATE STATE-POP 
= ; CAPITAL’. 
04 LINE-S-mSG-44. 
OZ E~4 PIC X€43] VALUE ‘CAPITAL-~POP? ’. 
O?7 SUE PIC xX VALUE ='’41E’. 
O02 E-2 FIC x{73 VALUE ‘’NO YES’. 
O2 ESC-4 PIC xX VALUE ='’27', 
OZ HT PIC xX VALUE ='°05’., 
Of DLE PiC xX VALUE =’ 40’. 
O2 FC PIC xX VALUE ='O2’, 
O2 ROUW-S PIC xX VALUE =’ 10’. 
O02 COLurin-464 PIC xX VALUE =’0S’, 
O04 LINHE~-4-756-1B. 
O2 E-4 FIC xX€26) VALUE ’ERROGR - STATE NAME INVALID’. 
@ LINKAGE SECTION, 
Of PROGRAM-INFORMATION-BLOCK. COPY PI674. 
O02 STATUS-CODE PIC 904) COMmP—4, 
O2 DETAILED-STATUS-CODE PIC 914) CORMP-4. 
O27 RECORD-TYPE REDEFINES DETAILED-STATUS-CUDE. 
03 PREDICTED-RECURD-TYPE PIC xX. 
O3 DELIVEREGD-RECORD-TYPE PIC X. 
OZ SucCesscdr-Ip PIC xXté). 
O2 TERMINATICN-INGDITATOR PIC xX. 
O02 LOCK-RILLBACK-INDICATOR PIC X. 
O2 TRANSACTIUN-1D. 
O3 YEAR PIC 7€4) COnmP-4. 
O3 TUDAY PIC 9C4) CorP-4. 
O03 HR-NIN-SEC PIC 9C9) COrP~-4. 
O02 DATA-DEF-REC-NAME PIC x(7). 
O2 DEFINED-FILE-NAME PIC xt7j. 
OF STANDARD-ASG-LINE-LERGTH PIC 904) COMP-4. 
OZ STANDARD-MSG-RUMRBER-LINES PIC 9(€4) COMP-4. 
O02 WURK-AREA-LENGTH PIC 9043 COPrP-4. 
O2 CUNTIAULTY-DATA-INPUT-LENGTH PIC 9$C4) COFP-4. 
O02 CONTINUITY-DATA-OUTFUT-LENGTH PIC 9(€4) COrmP-4. 
OZ WORK-AREA-INC PIC 924) COrP-4. 
O2 COUNTINUITY-DATA-AREA-INC Pic 9(43 Ctvir-4. 


O2 SuttCess-UnTT-Ib. 
O3 TRAHSACTIUN-DATE. 


04 YEAR PIC ¥¥, 

O4 MONTH PIC #9. 

o4 TOmAT Pte 99, 

G3 TIFE-GF-DAY. 

04 HUUR PIC 99, 

@ O4 MINUTE PIC #9, 
04 SECOND PIC 3. 
O3 UniQgue-SurF EX PIC 799. 


Figure 3—27. Sample COBOL Action Program ACT? (Part 1 of 3) 
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O2 SOURCE-TERAINAL-CHARS. 
O03 SOURCE-TERMINAL-TYPE 


PIC X. 


O3 SOURCE-TERMINAL-MSG-LINE-LENGTH PIC 9(4) COMmP-4. 
O03 SOURCE-TERNINAL-MSG-NUMBER-LINES PIC 904) COMP-4. 
INPUT-FIESSAGE-AREA. COPY InAZ74., 


O02 SOURCE-TERAINAL-10 
O02 DATE-TIME-STAMP. 
O3 YEAR 
03 TODAY 
O3 HR-MIN-SEC 
O02 TEXT-LENGTH 
O02 AUXILIARY-DEV-1D. 


PIC x(4}). 


PIC 94) COMP-4, 
PIC 9€4) COmP-4. 
PIC 9(9) LOMP-4, 
PIC 9(4) COnP-4. 


O3 FILLER PLC Xs 

O03 ALIX-DEV-NO PIC xX. 
OZ TRANSACTION-CGDE PIC x, 
O2 FILLER PIC xX. 
O2 STATE-NAME-IKk PIC AC44). 
HWURK-AREA. 
OZ STATE-NAME PIC At414). 
O2 STATE-PUP PIC ¢(8). 
O2 CAFITAL PIC AC25). 
OUTPUT-MESSAGE-AREA. COPY OFA7 4, 
O2 DESTINATICR-TERNINAL-ID PIC XC4). 
O2 SFS-ORPTICNS PiC XC2). 
O02 FILLER PIC xt2). 
O2 CUNTINUOUS-CUTFUT-CODE PIC x(4J. 
O02 TEXT-LENGTH PIC 9€4) COmP-4., 
O2 AUXILIARY-GVEVICE-iB. 

O3 Adx-FURC TION tae &* 

O3 AUX-DEVICE-NO PIC xX. 


O2 LINE-O-GuT PIC xXt4). 
O2 LINE-4-GUT. 


O3 E4-GuT PIC xX(37). 
G3 CUNTROL-4 PIC x€4j. 
O3 CONTRIOL-Z PIC xC4). 
O2 LINE-3-OUT. 
O3 FILLER PIC xx. 
OS STATE-MATIE PIC ACi4). 
O3 FILLER PIC xt4jJ. 
O3 STATE-FOP FIC 39,999,999, 
O3 FILLER PIC x£4). 
G3 CAPITAL PIC Atzs). 
O3 COnTROL-3 PIC x€4). 
US CONTROL~-4 PIC xt4). 
Oc Link-S-Gut PIC xtl2e73. 
CONTINUITY -BATA-GREA. 
O2 CAPITAL PIC At25). 


PROCEGURE DIVISION USING FPROGRAM-INEORMAT ISN-BLOCK 
INFUT-FRESSAGE-SREA WORK-ARES GUTPUT-NESSAaGE-akEA 


CONTIANULTTY-GATS-aRER. 


GET-STATE-RECORD. 
CALL GET’ USING STATE WORK-AREA STATE-NATIE-IN, 


IF STATUS-CODE EtQuar 4 G60 


TO PRICESS-ERROR. 


Figure 3—27. Sample COBOL Action Program ACT1 {Part 2 of 3) 
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CUILD-GUTPUT-HESSAGE. 
MOVE LINE-O TO LINE-O-GuUT. 
MOVE LINE-4-75G-714 TO E4-GUT. 
MOVE LINE-0O TG CUONTROL-4 CONTRUL-—Z. 
AGE LINE-3-UUT . 
MOVE CORRESPONDING WORK-AREA TO LINE-3-OuT. 
MOVE LINE-O TO CONTROL-S CONTROL-4. 
MOVE LIkE-S-m56-44 To LINE-5-OuT. 
SAVE-CONTINLILTTY-DATA. 
MOVE CAPITAL OF WURK-AREA To CAPITAL GF CONTINUITY-DATA-AREA. 
TERA-WITH-EXTERNAL-SUCCESSOR. 
WIVE “E’ TO TERMINATION-INDICATOR. 
MOVE *“ACTZOO0’ TO SuccessorR-1D. 
CALL “RETURN, 
PROCESS-ERROGR. 
MOVE LINE-O TO LINE-O-OuUT. 
NOvVE LINE-4-MSG-4B8 TO LINE-4-0UT. 
MOVE ERRGR-~TEAT-LENBTH TO TEXT-LENGTH OF OUTPUT-RMESSAGE-AREA. 


TERMINATE-RORMALLY. 
CALL “RETURN?’. 





Figure 3—27. Sample COBOL Action Program ACT?! (Part 3 of 3) 
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Ce a eee ee 
IDENTIFICATION DIVISION, 
PROGRAMN-1ID. ACT2. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COPMPUTER. UNTVAC-OS3. 
OBJECT-COMPUTER. UniIvac-0S3. 
DATA OIVISION. 
WORKING-STORAGE SECTION. 


77 
04 


LINK 
04 


CITY PIC AC7) VALUE ’CITY’. 


02 
02 
02 
02 
02 
02 
02 
02 
O02 


DLE-4 
PCAC-4 
ROW-O- 4 
COLUPIN- 
DLE-2 
PCAC~2 
RiJW-O-2 
CULUFAN- 
FILLER 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


O- 4 


o=2 


AGE SECTION. 


PROGRAM-INFUORMATION-BLOCK. 


02 
02 
02 


02 
02 
02 
02 


O02 
02 
02 
02 
02 
O02 
02 
02 
02 


O02 
O02 


STATUS-CODE 
DETATLED-STATUS-CODE 
RECORD-TYPE REDEFINES DETAILED-STATUS-CODE. 
O3 PREDICTED-RECORD-TYPE 
O3 DELIVERED-RECORD-TYPE 


SUCCESS 


GR-ID 


EP a a 8 


XK 


TERMINATION-INDICATOR 


LOCK-ROLLBACK-INDICATOR 


TRANSAC 
03 YEAR 


TIOGN-1D. 


03 TUDAY 


O03 HR-f 
DATA-DE 
DEFINED 


IN-SEC 
F-REC-NAME 
-FILE-NAME 


VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 
VALUE 


40’. 
OS’. 
00’. 
700’. 
740°. 
70S’. 
700’. 
QO’. 
SPACES. 


COPY PIB7/4. 


STANDARD-MSG-LINE-LENGTH 
STANDARD-MSG-NUMBER-LINES 


WORK-AR 


EA-LENGTH 


CUNTINUITY-~OATA-INPUT-~LENISTH 
CONTINUITY-DATA-GUTPUT-LENGTH 


WORK-AR 


EA~IMI 


CONTINUITY-DATA-AREA-INC 
O2 SuccesS-UNIT-ID. 
O3 TRANSACTIUN-DATE. 


03 UNI 


SUURE-TERMINAL-CHARS. 
O3 SOURCE-TERMINAL-TYPE 


O04 YEAR 
04 MONTH 
04 TOURY 


TIWE-UF-DAY. 


04 HOUR 

O4 MINUTE 

04 SECOND 

QUE-SUFF IX 


3-127 
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PIC 904) COMP-4. 
PIC 9€4) COrP-4. 


PIC 
PIC 
PIC 
PIC 
PIC 


PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 
PIC 


PIC 
PIC 
PIC 
PIC 
PIC 


PIC 
PIC 


PIC 


O3 SGURCE-TERMINAL-MSG-LINE-LENGTH PIC 
O03 SUURCE-TERMINAL-MSG-NUMBER-LINES PIC 
INPUT-GESSAGE-AREA. COPY IfA74. 


SOURCE - 
DATE-TI 
O3 YEAR 


TERMINAL-1D 
PE-STASIF . 


O03 TuUOAY 


O3 HR-f 


IN-SEC 


Xs 
Xe 
XC6). 
Xe 


Xe 


9C€4) COnP-4, 
9C4) COMP-4. 
9C9) COMmP-4. 


XC7 J. 
XC7 J. 


9C4) COMP-4. 
9C4)3 COrP-4. 
9043 COrP-4. 
9€4) CORP-4. 
904) CORP-4. 
9€4) COMnP-4. 
9€4) COMP-4. 


eee 
be ae 
ae 


99. 
99. 
99. 
999. 


Ke 


904) COrP-4. 
9(€4) Core-4. 


PIC XC4). 


PIC 9C€4) COrMP-4. 
FIC 904) 
PIC 9€9)3 COMP-4. 


Figure 3—28. Sample COBOL Action Program ACT2 (Part 1 of 2) 


COmP-4, 
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O2 TEXT-LENGTH 9(€43 COMmMP-4. 
O2 AUXILIARY-DEV-ID. 
OS FILLER 
O3 ALIX-DEV-NO 
O2 FILLER Pit Xe 
O2 NOU-POP PIC AR. 
OZ FILLER PIC xXx. 
Q2 YES PIC Xxx. 
O04 WURK-SREA. 
O2 CITIES ACZS). 
O2 CIiTY-F oP a ae oe 
OZ STATE CG AC44). 
O4 DUTPUT-RESSAGE-AREA. COrFY oriea74. 
O02 DESTINATION-TERAINAL-1D PIC xC€4}. 
Of SF 5-OF TIONS PIC xC€2)j. 
OZ FILLER PIC x€2). 
O2 Cos Tinlgus-GQuTFuT-Cope PIC xXC4}. 
2 TEXT-LENGTH | PIC 9€43 CuctP-4. 
O2 AUXILIARY-OEVICE-IO. 
O3 AUX—FUNCTICN PIC X. 
O03 AUZ-DEVICE-ND PIC xX. 
O2¢ E=-4 ag ae 
G2 CAFPITAL-POP Pic 
O44 CONTINUITY-BATA-AREA. 
O2 CAPITAL PIC 
FROCEDURE DIVISION uSING PROGRAM-INFURMATION-BLOCK 
INPUT-FESSAGE-AREA WORK-AREA GUTPLUT-RESSAGE-AREA 


COMTINUITY-DATA-AREA,. 
CHECK -RESFONSE. 


IF YES EQUAL ‘YES’ 60 TO GET-CITY-RECORD. 

MOVE ZeR TO TEXT-CENGTH OF OUTPUT-NESSAGE-AREA. 

60 TOG TERMINATE-NOURMALLY. 
GET-CITY-RECORD. 

CALL ‘GET’ USING CITY WORK-AREA CAPITAL. 
BUITLO-OGUTFPUT-NESSAbBE. 

MOVE LINE-4 TO E-4. 

MOVE CiTy-FPOrP To CAFITAL-POPR. 
TERMINATE-NURGALLY. 

CALL ’RETURR’. 





Figure 3—28. Sample COBOL Action Program ACT2 (Part 2 of 2) 


3.15.3. Continuous Output Example Using Delivery Notice Scheduling 


Figure 3-29 reproduces a compiler listing of a sample COBOL action program, PRINT, 
written to illustrate a number of points relating to the use of the continuous output option. 
The primary function of PRINT is to prepare three types of output messages by processing 
customer order information entered at the terminal against an indexed file, and to cause 
these messages to be listed as continuous output at the originating terminal. A parameter 
on the initial input message can cause the printing to be sent to a COP. The routine 
performing these functions uses delivery notice scheduling to determine whether output Is 
to continue or error processing is to be invoked after delivery notice of each message is 
received from IMS 90. So long as the output continues successfully, PRINT terminates in 
external succession, having named itself as successor to create the next output message | r 
to be printed. When end-of-file is reached, PRINT terminates normally, with an output 
message to the operator that printing is completed. 
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If an unsuccessful delivery notice is received, PRINT does not terminate immediately but 

first reports an output error to the terminal operator and allows him to control further 

output, terminating in external succession to await his reaction. He may react by breaking 
_ off, resuming, or terminating the transaction normally. 


When it is first activated by action scheduling as the result of the terminal operator's 
initial keyin, PRINT expects to process an input message in the following form: 


PRINT t-file-name t-order-number init-terminal [COP] 


where: 


PRINT 
is the transaction code that causes PRINT to be scheduled. 


t-file-name 
Is the name of the conventional file to be accessed. As stated, the file is an 
indexed file; PRINT expects to process a file named ‘ORDRFIL’ and validates the 


t-file-name keyed in (line 268, Figure 3-29). 
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t-order-number 
Is an order number used as a key search argument in positioning the file for 
retrieval (line 272). 


init-terminal 
Is a configured identification to the originating terminal, used in the switching of 
output error messages to the operator (line 355). 


COP 
ls the 3-character code input by the terminal operator to designate that what is 
to be output is to be printed on the COP. Notice its use in line 302. 


On initial activation, PRINT passes control to the BEGIN-TRANS routine, which initializes 
certain fields of the continuity data area and work area and validates the name of the file 
to be processed. BEGIN-TRANS positions the file for sequential processing and, retrieving 
a record, processes it and the input message. It forms a customer record, a product record, 
or a total record (according to the path that control follows) in the output message area; 
control then passes to the CREATE-CONTINUOUS-OUTPUT routine (line 301). 


Here, if the terminal operator has not keyed in COP to cause the output message to be 
directed to a communications output printer, the routine moves the hexadecimal value C3 
to the AUX-FUNCTION byte of the AUXILIARY-DEVICE-ID field of the OMA header (line 
303). This causes the output message to be written as continuous output on the screen of 
the primary device. Otherwise, line 304 moves the hexadecimal value F7 to this byte, to 
cause print-transparent continuous output on a COP, and line 305 moves a 1 to the AUX- 
DEVICE-NO byte of the AUXILIARY-DEVICE-ID field of the OMA header to specify the COP 
relative number as defined in the ICAM generation. Line 306 moves into the 
CONTINUOUS-OUTPUT-CODE field of the OMA header a 4-character value, developed 
during processing, that will identify this output message when received in the 5-byte input 
message that IMS 90 creates for the next activation of PRINT after attempting to deliver 
the message as specified. 


After specifying external succession (line 308) and moving its own program name into the 
SUCCESSOR-ID field of the PIB (line 309), PRINT terminates to await reactivation by action 
scheduling. 


On receiving the 5-byte input message from internal message control, action scheduling 
reactivates PRINT. On examining this input message, PRINT checks the first four bytes to 
ensure that it is processing the expected input (line 348) and then proceeds to verify that 
the delivery attempt was successful. It does this at line 336 by comparing the fifth byte of 
the input message (DEL-NOTICE-STATUS) against the value ‘A’. This value, which it has 
established for the constant SUCCESSFUL-DEL-NOTICE in a 77-level entry in the working- 
storage section (line 10), is the translated value for a successful delivery notice status 
(hexadecimal 81) reported to IMS 90 by ICAM. If delivery was unsuccessful, PRINT does 
not attempt to determine the reason but proceeds to send an error message to the 
terminal operator. If an initiating terminal is specified, error messages are switched to that 
terminal. On successful delivery, it resumes processing. 
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00004 IDENTIFICATION DIVISION. 

00002 PROGRAM-ID. PRINT. 

00003 ENVIRONMENT DIVISION. 

00004 CONFISURATION SECTION. 

0000S SOURCE-COMPUTER. UNIVAC-OS3. 

00006 OBJECT-CORMFUTER. UNIVAC-OS3. 

00007 DATA DIVISION. 

00008 WORKING-STORAGE SECTION. 

O0O009 77 PUS-GE PIC X VALUE ’°G’*. 
00040 77 SUCCESSFUL-DEL-NUTICE PIC X VALUE =’C4’, 
00044 04 =(TOTAL-POS. 

00042 O02 DICE-TP PIC xX VALUE =’ 40’, 
00043 O2 FLNC-TP PIC xX VALUE ='04’., 
00044 OZ Y-TF PIC xX VALUE =’00’. 
00045 O2 X-TP PIC xX VALUE ='33’. 
COO046 O41 HEADER-LINES. 

00047 O2 URDER-LINE. , 

00018 O03 HUME-PUS-CLEAR. 

00049 OS BICE-HPC PIC xX VALUE =’ 40’, 
00020 O05 FUNL-HFC PIC xX VALUE =‘03’. 
0002 4 OS Y-HPC PIC xX VALUE =’00’, 
00022 OS X-HPC PIC xX VALUE ='00’, 
00023 O3 MIDDLE-CuL-FPOS. 

00024 OS DIiCe-mep PIC x VALUE =’ 40%, 
60025 OS FUNC-ACP PIC xX VALUE =’O2’. 
000246 OS Y-fice PIC x VALUE ='’00". 
00027 OS X-nmcP PIC xX VALUE =’37’. 
00023 03 P-ORDER-HEAD PIC XC10) VALUE ’ORDER fi 
00029 03 P-URDER-NO PIC 9C7). 

00030 03 NEWLINE-3. 

00034 O05 DICE-N3 PIC X VALUE =’ 40’, 
00032 OS FURL-NS PIC xX VALUE =’04°, 
00033 0S Y-N3 PIC X VALUE =’02’. 
00034 OS X-N3 PIC xX VALUE =‘00’,. 
00035 O2 MAIL-LINES. 

00036 03 P-HAME PIC x€20). 

00037 O3 NEWLINE-A. 

00033 05 DICE-N14 PIC xX VALUE =’ 40’, 
00039 O5 FUNC-N4AA PIC Xx VALUE =’04’, 
00040 OS Y-N4A PIC x VALUE =‘00°. 
00044 OS X-N4A PIC X VALUE ='OO’. 
00042 03 F-ADOR PIC xce4S). 

00043 O3 NEWLINE-&S. 

00044 0S OICE-N18 PIC x VALUE =‘ 40°’, 
00045 OS FUNC-N4B PIC xX VALUE =’04', 
00046 O5 Y-N46 P{[C x VALUE =‘00", 
00047 OS X-N4B PIC xX VALUE ='’060’, 
000486 O03 F-CITY PIC xt 4S]. 

GOG0049 O3 P-2ZI1P PIC x(S3). 

00050 O3 NEWLINE-2. 

00054 05 DICE-N2 PIC xX VALUE =’40’,. 
00052 05 FUNIZT-NZ PIC x VALUE =’04’, 
00083 OS Y-n2 Pic xX VALUE =’04', 
00054 OS X-NzZ PIC x VALUE ='06/, 
00055 O2 HEADING-LINE. 

00GS56 O03 PROGUCT-HEADING PIC xli?j 

GO0S7 VALUE ’ PRODUCT 
QO0S8 O3 Url t-COST-HEADING PIC xt443 

GOOO0S9 VALUE ‘’LIN]T-COST 7°. 
00060 OS AMGUANT-HEADIANG PIC xt] 

00064 VALUE ’SoGUNT 7, 
00062 O03 SUB TOTAL-HEADING PTC xt 40) 

60663 VALUE ’SUBTOTAL °. 


Figure 3—29. 





Sample COBOL Action Program Performing Continuous Output (Part 1 of 7) 
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IMS 90 APPLICATIONS Update A 
00064 O3 SPACING PIC X€33 VALLE ’ Ps 
00065 O3 TOTAL-HEADING PiC xtdj VALUE ° TOTAL °. 
O00E4 O3 NEYLINE-C, 
OG067 O5 DICE-Nic PIC xX VALUE =’ 40’. 
O0GS3 OS Fuhl-naic FIC 2 VALUE ='O4’. 
CO08S G5 Y-N4ac PIC xX VALUE =’OO’, 
00076 OS ¥-Nal ees Wee VALUE =’OO*. 
00074 O04 ERROR-POUSTTION,. 
0007 2 O3 DIite-EP PIC x VALUE =’ 40’, 
00073 OS FLUAC-EP PIC x VALUE ='O4’, 
00074 O03 Y-EF Pic x VALUE =’ OG! 
(0075 O3 X-eEP PEG x WALUE =/O0O'°., 
OOG76 LIKKADGE SECTION. 
OG077 O44 PROGRAN-INFOURMATION-SLOCK. COPY PIB?4., 
OG78 Of STATIS-COBE PTe $41 Cdrifb-a4, 
OOO? F OZ DETALLED-STATUS-CODE PTC $t4) Ccwip-4. 
OOO8Y Of RECERO-TYPE REDEF INES DETATLED STATUS - ‘COoGe. 
OOS 4 O3 PREDICTED-RECORD-TYPE PIC Ks 
COB8?e O3 BDELIVERED-RECORD-TYFE PE Mx 
GQU08S O2 SuCCESSOR-1D PIC x63. 
COOdS Of TERMINATION-INGICATOR PIC x. 
OnogS OF LOCK-ROLLBACK-]NOICATIOR PIC xX. 
OnGeS Of TRasséacTfOu-Iib. 
Gogg? OS YEAR PIC 94) voP-4. 
OOOH on Vee PIC 9044 COMmP-4, 
OO08F 3 —TIN-SEC Pic 9C(9) CorP-4, 
OOGP Oo? ae HEE = ~REU RAKE PIC Xt7). 
GOO? 4 G2 OGEFINED-FILE-NATIE Pi RS oe 
GOOG? 2 OF STAKDARG-M55-LINE-LENGTH FIC £4) COMmP-4. 
Haaes O2 STANDARD-NSG-NUABER-LINES PIC C4) COHAP-4., 
QO0y4 OP WORKR-ARER-LENGTH FIC 904) COmP-4. 
OGO95 G2 CONTINULTY-BDATA-IANPLT-LEMGTH PIC $(41 ComMrF-4. 
OOGeS Of COsTiswigy-GatTa-GutPuT-LEnoTH PIC 9704) COMP-4. 
OOO? OZ WORK-ARES-INC PiC °C43 COMP-4. 
CO07% OZ CUNTINUETY-DATAa-AREG-INC PIC ¥t4] COMmMP-4. 
GOOF O?2 SucCCeEss-UNIT-iB. 
00 40% OS TRANSACTIOGN-DATE. 
oO4Q4 4 YEAR FIC 99. 
OO4702 O4 TINTH PIC 99, 
009403 G4 TODAY PiC 99. 
09404 O3 Tine-GF-DaAy. 
00405 4 HOUR Pic 99. 
OO 4046 O4 RMINUTE FIC 99, 
00407 O4 SECOND PIC $9, 
OO402 O3 UNLQUE-SUFFIX PTC 999, 
BOO 409 OF SUURCE-TERMIRAL-CHARS. 
OO440 O3 SUGURCE-TERMINAL-TYPE PIC X.« 
00444 O03 SOURCE-TERMINAL-MSG-LINE-LENGTH PIC 9043 COWP-4. 
00442 O03 SOURCE-TERMINAL-MSG-NUMBER-LINES PIC 904) COMP~4. 
09443 04 JHNPUT-FAESSAGE-AREA. COPY IMA74. 
00444 Of ‘SOURCE-TERMINAL-ID PTC XL4j. 
00445 O2 DATE-TINE-STAAP. 
00446 03 YEAR PIC 9(4) COMP-4. 
00447 O3 TODAY PIC 9$(€4)3 COMP-4. 
00448 O03 HR-MIN-SEC PIC 9C7) CUmP-4. 
OO449 O02 TEXT<-LESGTH PIC 9€43 COTPMP-4. 
00420 OZ AUXILIART-DEV-ID. 
O0424 O03 FILLER PIC X. 
OO422 G3 AUX-DEV-NUD PIC xX. 
00423 OZ TRANS-TERXT. 
OG424 OS TRANS-CODE FIC x¢Sj. 
60425 OS FILLER FIC x. 


Figure 3—29. Sample COBOL Action Program Performing Continuous Output (Part 2 of 7} 
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IMS 90 APPLICATIONS Update A 
00424 OS T-FILE-NAME PIC xc?7). 
00427 OS T-URDER-NO PIC ¥C7). 
00423 O5 FILLER PIC xC4iJ. 
OO429 O5 INIT-TERMINAL FIC xXC4). 
064390 OS FILLER PIC xt 434 
OO4F34 65 AT-CUP FIC xt3j. 
00432 OZ ACTION-TEXT REDEFINES TRANS-TEXT. 
60433 OS COMMAND-COBE PIC x(SJ. 
O60 134 O05 FILLER PIC ACZI. 
00435 05 A-ORDER-NO PIC 9C7). 
00436 OS FILLER PIC xl45). 
00437 O2 DEL-NOUTICE-TEXT REDEFINES TRANS-TEXT. 
0043¢ O05 DEL-koTice-CuDdE FIC xC4j. 
0043? OS DEL-NOTICE-STATUS PIE Xs 
00440 OS FILLER PIC xti24). 
00444 O01 WORK-AREA. 
00442 O3 RECORDO-AREA. 
00443 OS RECURD-KEY. | 
00444 O7 K-OGRDER-AO PJCC s37C7) COmP-3. 
00445 O7 K-CIRDER-ENTRY PIC 599° COMP -3, 
00446 OS FILLER PIC xt74)J. 
00447 O3 ERROR-IND PIC xX. 
00448 04 QUTFUT-MESSAGbE-AREA. COPY OFA4., 
00449 O2 DESTINATION-TEROINAL-ID PTC XC4). 
00450 Of SFs-dr TIGANs PIC X£2}). 
0015 4 Of FILLER Pic x2). 
C0452 O02 COUNTIKUDUS-UUTFUT-CODE FIC xt4}. 
00453 O2 TEXT-LENGTH PIC ¥C43 COMP-4. 
00454 O2 AUXILIARY-DEVICE-ID. 
06455 O3 ALIX~FUACT ION PIC X. 
00456 O03 AUx-DEVICE-N PIC) Xs 7 
OO 457 O3 MESSAGE-4. © 
90453 OS FILLER PIC xt4éJ. 
0045? O05 m-UARDER PIC 9€73. 
00460 O05 FILLER FIC xi4). 
00464 OS M-NaAE PIC x(20). 
00462 OS FILLER PIC x43. 
60463 OS A-ABDOR PIC x(153). 
OO464 OS FILLER FIC xt4]. 
90445 oS m-CiUTy PIC x€453. 
00466 OS me-ZIF PIC x¢Sj. 
UO467 OS FULLER FIC xf£444). 
00468 O3 MESSAGE-f REDEF INES MESSsbe-4. 
0046? OS P-ERAND PIC x£ 473. 
OO47U O05 Cus PIC $¢,¢39.979., 
OG 4? 4 O5 FILLER PIC xXt23. 
OO 42g OS Suit PIC ZZz. 
Oa47? 3 OS FILLER PIC x¢2). 
C0474 OS P-SuaTOTAL FIC 2,$38, 393.99, 
UC4A7S US HEXTLINE-2 PIC xC4]., 
OO476 O5 FILLER PIC xtC 454). 
OG477 QO3 MESSAGE-3 REDEFINES MESSAGE-4. 
o047¢6 O5 CuRSGR-PUS PIC x(4]. 
OO479 S&S T-TOTAL PIC $2,385, 388.99. 
OO 460 O5 VaLiIbiTy-CHark PIC uk « 
O048 f OS FILLER PIC xL4860). 
COB O3 MESS4age-4 REBEFIKES MESSAGE-4. 
UG4es OS POSiTIUN-4 Pic x(4]. 
OO484 OS HEADER-4 PIC x(42]., 
OO485 OS CORDER-4 FIC C7). 
00486 O5 FILLER FIC xe4#S3i. 


Figure 3—-29. Sample COBOL Action Program Performing Continuous Output (Part 3 of 7) 
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OO 487 GOS MESSAGE-S REDEFINES AESSAGE-4. 
06488 65 eee PIC X43. 
OO 4B9 OS KHEADER-5S Fic xCi?). 
OG490 OS TERMN-KAME FIC Xi4d. 
Gora OS FILLER PIC x0 479) 
Oo43¢ O3 PiESS4o&£-56 REDEF INES ME SssSaAbe-4 
OOAsg OS FOSLT IONS Pic xt4i]. 
OU 4ys OS Baan -GUTPuT PIC xC€5S33 
eae: HS FELLER PIC 2f 449) 
OU 70 OF MProcsaage-/ REDE ITRES RESSAabE-4. 
Od 4 7 G5 POSTTTUN-7 PIC xt4), 
a0 47H OS ReESUGE ERROR -GUTPOUT PIG xt24i, 
OO 4yy OS FULLER PIC. 4C47 63% 
GaeOs O3 HESS4OR-G REDEFINES MESSAGE-4 
OG 4 GS POSLITION-S Pic xlad). 
GOLGL OS ENOG-OUTRUT PIC xt23). 
O23 OS FILLER Plo xtard. 
OLS OS MESSAGE -y REDEF INES FieDSSSik-4., 
OOo?SOh ws Sete PIG #04). 
QOZGS OS fMPuT-ERROR-GUTFUT Pit xC323. 
Gora? oS FELLER Pit KC V/ 0 ds 
HVS OS MESSa45€-16 Reber leES MESSAGE-4. 
oes OS POSLVICIN- 10 Pit xt4). 
QOZ AG OS FILE~ERRUOR-GUTFUT PIC x€42), 
Oaz 44 OS FULLER PIC x( 460), 
00242 Of CONTINUITY-DATA-ARES. 
00243 03 CUSTORMER-RECORD. 
00244 OS C-KEY PIC XtéJ. 
00245 05 C-ID PIc x¢CS). 
00246 05 C-NAME PIC x(20). 
00247 O05 C-ADDR PIC xC15). 
002418 OS C-CITY PIC xC45J). 
00249 OS C-Z1P PIC xtSj. 
00220 OS t-TOTAL PIC S9t7IU79 CoOmr-3. 
0022 fj OS FILLER PIC xX€414). 
00227 O3 PROBUCT-RECORD. 
00223 GS P-KEY PIC xC6J. 
O02 24 O05 Propucl PIC XC4/73). 
00225 05 UNIT-COST PIC S9C3IVOP COrP-3. 
00226 OS ANDUNT PIC S97 COFP-3. 
00227 05 SUBTOTAL PIC S9C7 399 COMP=-3. 
00224 OS FILLER PIC X(47)}). 
00229 O03 CURRENT-ORDER-NO PIC $9(€73 COMP-3. 
00230 O3 CURRENT-CORT-CODE REDEFINES CURRENT-ORDER-NO PIC XC€4). 
0023 4 O03 CURRENT-ENTRY-NO PIC S999 CUMP-3. 
00232 O03 CURRENT-TOTAL PIC S9C7IV99 COMF-3. 
00233 O3 INIT-TERM PIC xXC4). 
00234 03 DEST-TERM PIC xC4J. 
00235 03 CORP-OUTPUT PIC x(3j. 
00236 O3 FILE-KEY. 
00237 05 FILE-KEY-4 Pic $9C73 COMP-3. 
0023¢ OS FILE-KEY-2 PIC S$9t33 COmP-3. 
00239 O3 FILE-NAME PIC x7). 
00240 O3 INFUT-TUOTAL PIC S¥C7IVU99 COMmP-3. 
0024 4 O3 BREAK-AODE PIC X. 
00242 O03 FPRIANT-DEST PIC X43). 
00243 PROCEDURE DIVISION USING PROGRAM-INFORMATION-BLUCK 
00244 INPUT-MESSAGE-AREA 
GOZ24S WURK-AREA 
00246 GUTPUT-MESSAGE-AREA 
600247 CONTINUITY-DATA-AREA. 


Figure 3—29. Sample COBOL Action Program Performing Continuous Output (Part 4 of 7) 
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IMS 90 APPLICATIONS Update A 
00243 EXARINE-INPUT. 
00249 IF TRANS-CODE EXUGL TO ’PRINT’ GO TO BEGIN-TRANS. 
0025” IF CORMAND-CODE EGUAL TU ’END ° 60 TG EXD-TRANS. 
0025 4 IF COMMAND-CODE EGUAL TO ‘BREAK’ GO TO BREAK-TRANS. 
00252 IF COMMAND-CODE EQ“UAL TU ‘RESUR’ GO TU RESUTE-TRANS. 
00253 IF DEL-NOTICE-CODE EGUAL TO ‘END *’ GO TG END-OF-FILE. 
00254 IF DEL-NUTICE-CODE EQgudéL TO CURRENT-CONT-CODE 
00255 GO TO DEL-NUOTICE. 
00256 MOVE ’INVALIO DELIVERY NOTICE CODE 
00257 TO INPUT-ERROR-GUTFUT. 
00258 66 TO DEL-NUTICE-ERROR. 
00259 BEGIN-TRANS. 
00260 MOVE O TO CURRENT-ORDER-NU 
0026 4 MAUVE O&O TO CURRENT-ENTRY-NU 
00262 MOVE O Td FILE-KEY-4 FILE-KEY-2. 
90263 nMivE O TO CURRENT-TOTAL 
OO264 MOVE O TO BREAR-TMOGOE 
00265 nove SPACES TO InlT-TERA 
00266 FOVE SPFALES To Desf-TerRN 
OO267 m0VE AT-COUP TO CoOoR-GUTPUT. 
00245 IF T-FILE-NAME NOT EGuAaL TO ’ORDRFIL’ GO To IkPUT-ERROR. 
0026? MOVE JAIT-TERMINAL TO ittlT-TERA. 
00270 MOVE SOGURCE-TERMINAL-IB TU PRINT-DES?. 
0027 4 IF JT-ORDER-NO NOT EGUAL TO LOW-VALUES AND SPACES 
00272 FUVE T-ORDER-—-NU TOG FILE-KET-4. 
00273 rOVE T-FUiLE-NAE TO FILE-NAME. 
00274 POSITIOn-FILE. 
OG275 CALL ‘SETL’ wSinG FILE-naAmE FOS-GE FILE-KEY. 
00276 IF STaTus-COGE EGuaL Td O GU TG READ-RECORD. 
G0277 MOVE “END ¢ TO CURREHT-COnT-CODE. 
00278 GO TO TUTAL-FRUOL. 
00279 READ-RECURD. 
00260 CALL ‘GET’ ising FILE-NANE RECORD-ARES. 
9025 4 iF STaATUS-CODE Egust TO 4 GO TO FILE-cRROR. 
C0232 IF STATUS-COGUE GREATER THAN 2 GO To FILE-ERROR. 
00283 IF STATUS-CODE EGual TO 2 60 TO END-cF-FILE. 
OO254 IF K-ORDER-ENTRY NOT Edua To OG GO TO PRODUCT-PROC. 
00285 MOVE RECOURD-ARES TO CUSTOMER-RECURD., 
OOZH4 IF CURRENT-TOTAL HOT Egual Tou 0 GO TO TOTAL-PRIC. 
OO?73G7 CUSTOMER-FROC. 
O02d¢ MOVE C-TOTaAL TO InPul-ToTAc. 
QUZB9 MOVE K-CRDER-NO TO CURRERT-URGER-NO. 
ONLI MOVE K-OGRDER-h To FILE-KEY-“4. 
OaLs 4 AQVE K-CRDER-ENTRY TO CURRENT-ENTRY-#O. 
COZ 72 MOVE K-GRDER-ENTRY Tu FILE-KEY-z. 
GassS AbD 4 TG FILE-KEY-2. 
O02 YS MOVE HEADER-LINES TO Mks5sGe-4. 
GOL9S NOVE CURRENT-CRDER-MO TO A-OURDER, 
C0276 ROVE C-NAGE TO PimNARE. 
GOOZS7 MOVE C-aApbR TO m-aOOR. 
00275 MOVE Ceci TO eC ETT. 
GOLF mOVE Ce?7iP (Q M-#IF. 
O0B00 MOVE 453 Ta TexT-LehiarH IN GuTPuUT-MESSAGE-AREA. 
HO304 CREATE-CURTISu0uUS-GUTPUT. 
OO3I2 IF COPeGuTeuT NOT EgurAe To * OOF 
GO303 MOVE °C TG AUxX-FUNCTION 
OOS3R4 ELSE Nave 'F*° TO Aux-ruRe TION 
GOSGS MNUVE 4 70 AUX-DEVICE-‘vG. 
00396 MOVE CuRRENT-CONT-CODE TG CONTINUOUS-OUTPUT-CUODE. 
OOSO07 EXTERNAL-TERAIT RATION. 
00308 POVE “&? FO TeRnisATIGR-INGICATOR. 
COSOF — MOVE ‘“PRINTO’ 7O SuCTESSOR-Ib. 
00349 CALL RETURN’. 


Figure 3—29. Sample COBOL Action Program Performing Continuous Output (Part 5 of 7} 
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00344 
00342 
00343 
00344 
00315 
00346 
003417 
003448 
00349 
00320 
00324 
00322 
00323 
00324 
00325 
00326 
00327 
00323 
00329 
00330 
0033 4 
00332 
00333 
00334 
00335 
00336 
00337 
00338 
00339 
003490 
0034 4 
00342 
60343 
00344 
00345 
00346 
00347 
00348 
00349 
00350 
0035 4 
00352 
00353 
00384 
00355 
00356 
00357 
00353 
00359 
00360 
0036 4 
00362 
00363 
00364 
00365 
00366 
00367 
00368 
00369 
00370 
0037 4 
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PRODUCT-PROC. 
MOVE K-ORDER-ENTRY TO CURRENT-ENTRY-NO. 
MOVE K-ORDER-ENTRY TO FILE-KEY-2. 
ADD 4 TO FILE-KEY-2. 
MOVE RECORD-AREA TO PRODUCT-RECORD. 
ADD SUBTOTAL TO CURRENT-TOTAL. 
AGVE PRODUCT TO F-BRAND. 
MOVE UNIT-COST TO COST. 
MOVE AMOUNT TO Nui. | 
MOVE SUBTOTAL TO P-SUBTOTAL. 
MOVE NEWLINE-A TO NEXTLIHE-2, 
MOVE CURRENT-CONT-CODE Td CUNTINUODUS-GUTPUT-CODE. 
HOVE S4 TO TEXT-LENGTH IN OUTPUT-FESSAGE-AREA. 
GO TG CREATE-CONTINUGUS-OUTPUT. 
TOTAL-FROC. 3 
IF INPUT-TOTAL EXudAL TO 0 MOVE CURRENT-TUTAL TO INPUT-—TOTAL. 
MOVE SPACE 70 VALIDITY-CHaAR. 
MOVE INPUT-TOTAL TO R-TUTAL. 
IF IMPUT-TOTAL NOT ESUAL TO CURRENT-TOTAL 
move ¢*’ TO VALIOITY-CHAR. 
MOVE TOTAL-POS TO CLURSOR-POS. . 
MOVE 22 TO TEXT-LENGTH IN OUTPUT-RESSAGE-AREA. 
MOVE O TO CURRENT-TUTAL. 
GO TO CREATE-CUONTINUOUS-OUTPUT. 
DEL-NOTICE. 
IF DEL-NOTICE-STATUS 
. GO TO FOSITION-FILE. 
GUTPUT-ERROR, 
NOVE ERROR-POSITION TO POSLTIUN-4. 
MOVE ‘OUTPUT ERROR WHILE TRYING TO PRINT GRDERS ’ TO 
HEADER-4. 


EQUAL TU SUCCESSFUL-DEL-NOUTICE 


MOVE CURRENT-ORDER-NO TO GRDER-4. 

MOVE 57 TO TEXT-LENGTH IN OGUTPUT-MESSAGE-AREA. 
DESTINATION-DETERRMINATION. 

IF INIT-TERM wOT ESUAL TO LUW-VALUES AND SPACES AND 

SOURCE-TERMINAL~ID 
60 TO SWITCH-ERROR-MSG. 

WOVE 4 TO BREAK-MUDE. 

IF ERRGR-IND EGUAL TG LOW-VALUE GO TO EXTERNAL-TERAINATION. 

IF ERROR-IND EWUAL TO 4 GO TO NORMAL-TERRMINATION. 
ABNCIRMAL-TERMINATION. 

MOVE °S’ TO TERMINATIGN-INDICATOR. 

CALL ’RETURN’. 
SWITCH-ERRGR-MSG. 

MUVE INIT-TERA TO DESTINATION-TERMINAL-1D. 

CALL ’SEND’ USING OUTFUT-RMESSAGE-AREA. 

IF STATUS-CODE MOT EQUAL TO 9 GU TO ABNORMAL-TERNINATION. 
CREATE-NULL-MS6. 

MUVE LUW-VALUES TO DESTINATIUN-TERMINAL-I1D. 

MOVE NEWLINE-A Tao POSTTIdH-4, 

MOVE 8 TO TEXT-LENGTH IN UDUTFUT-rMESSAGE-AREA. 
NORRAL-~ TERMINATION. | 

MOVE 7°? TO TERMIMATIUN-INDICATOR. 

CALL ‘’RETURN’. 
END-JF-FILE. 

MOVE 4 TO ERRGR-ItD. 

MOVE ERROUR-POSITION TO FOSLITIOGA-S. 

ROVE ?FRieT COSPLETED AT ° TO HEADER-S. 

MOVE FPRINT-DEST TO TERM-NAHE., 

MOVE 34 TO TEXT-LENGTH In GQUTPUT-NESSAGE-AREA. 

GO TO DESTINATION-DETERMINATION. 


Figure 3—29. Sample COBOL Action Program Performing Continuous Output (Part 6 of 7) 
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00372 
00373 
00374 
00375 
00376 
00377 
00378 
00379 
00380 
0038 4 
00382 
06383 
00384 
060385 
00386 
00387 
00368 
OO3BF 
OO3 70 
0039 4 
C0372 
00393 
COSTS 
003975 
OOSF6 
CO397 
COS?7S 
OO399 
00460 
00406 4 
00402 
00403 
00404 
00405 
00406 
00407 
00408 
00409 
00440 
00444 
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BREAK-TRANS. 
MOVE 4 70 BREAK-MODE. 
MOVE “BREAK ERFORCED - RESUNE REWUIREO TO 

TO BREAK-DUTPUT. 

FUVE 64 TO TEXT-LENGTH In GUTFPUT-MESSAGE-AREA. 
GU TO EXTERNAL-TERMINATIORN. 

RESUME-TRANS. 
IF BREAK-MODE caval TO 0 GO TO RESUME-ERROR. 
MOVE O TU BREAK-TNDE, 
IF A-URDER-NOG cCOUAL TO LUW-VALUES GR 

GG TU FUSITION-FILE. 

MOVE A-URDER-wG TO FILE-KEY-4. 
MOVE OG TO FILE-KEY~-z. 
NOVE O TO CURRENRT-TOTAL. 
GO TO FOSTTian-F Ive. 

RESUME-ERRUR. 
FiOVe ERROR-POSTTIGN Ta FOSITION-7. 
MOVE ’RESUHE INVALID ~- IGNORED’ TO RESUME-ERROUR-OGUTPUT. 
ROVE S32 TO TEXT-LENDTH Ik GUTPUT-MESSAGE-AREA. 
GU TO NURMAL-TERMIAATION. 

END-TRANS. 
NOVE ERRUR-FOSLTTION TO 
MUVE ~°PRINT TRANSSC TION ENDED? 


CONTINUE PRINTING’ 


SPACES 


FOSLTICN-&. 
TU ENGD-OuTPuT. 
AREA, 
GU TU MURAL -TERAGNATION., 
IHPUT-ERROR,. 
MOVE ’°INPUT Ik - PRINT AUT BEGUN’ 
TO JIRPUT-ERROR-GUTPUT. 


ERATIR 


DEL-NUTICE-ERRGR. 
MOVE 2 10 ERRUR-IND. 
MUVE ERRGR-FOSTITIOn To POSITTiIGn-¢F., 
MOVE 460 TO TEXT-LERGTH IN GUTPUT-IIESSAGE-AREA. 
GO TO DESTINATION-DOETERMINATION. 
FILE-ERROR. 
PUVE 2 To ERRUR-INGD. 
MOVE ERRUR-POSITICN TO FOSITICR-10, 
ROVE “FILE ACESS ERRDUR - TRANSALTIOn TERMINATED’ 
TO FILE-ERRUR-OUTPUT. 
MOVE SO TU TEXT-LENGTH In OGUTPUT-RESSABE-AREA. 
GO TO DESTIARATIUN-DETERMINATIOUN., 





Figure 3—29. Sample COBOL Action Program Performing Continuous Output (Part 7 of 7) 
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PRINT terminates in external succession after output to the operator of a message 
informing him of unsuccessful delivery of the last continuous output message (from line 
349). It expects him to enter either the command ‘RESUM’ (line 252) or the command 
‘END’ (line 250) and is prepared to process one of these as its next reactivation. If he 
enters the command ‘END’ (line 396), the program terminates with normal succession. If 
he enters the command ‘RESUM,, the program allows him to continue printing from where 
he left off, or from an earlier order number specified as an optional parameter of the 
‘RESUM’ command (line 135). 





PRINT voluntarily terminates abnormally, with a SNAP dump, whenever: 
= it receives an unexpected input message on activation (line 258); 


= an attempt to access some file other than ‘ORDRFIL’ (line 268) after having output a 
message to the operator (line 397); 


= an unsuccessful return has been made to the STATUS-CODE field of the PIB after 
issuing the GET function to ORDRFIL (lines 275, 280) - again, after having notified 
the operator (line 405); or 


=» §= any of its error or warning messages switched to the terminal operator have not been 
successfully sent (line 357). 


© 3.15.4. QOutput-for-Input Queueing Example 


Figure 3-30 reproduces a compiler listing of a sample COBOL action program, BEGIN1, 
that illustrates a method of directing a print transaction using continuous output to be 
initiated at another terminal, using output-for-input queueing. BEGIN1 also provides for 
notifying the operator of the originating terminal whether the print transaction has been 
successfully initiated at its destination. 


When BEGIN1 is activated at the originating terminal, it expects an input message in the 
following format (lines 61-65): 


BEGIN dest-terminal text 


where: 


BEGIN 
Is the 5-character transaction code entered by the terminal operator to activate 
BEGIN1 (specified to the configurator in the TRANSACT section). 


dest-terminal 
Is the 4-character terminal-id of the destination terminal, at which the 
continuous output print transaction is to be initiated. (This must have been 
assigned in the ICAM network definition.) 
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text 
Is the alphanumeric text input by the originating terminal operator. This text is 
the input message expected by the print transaction that is to perform 
continuous output at the destination terminal and must begin with the 
transaction code that will cause scheduling to initiate it. 





On activation of BEGIN1 the MOVE-MESSAGE procedure forms an output message to be 
queued as input for the destination terminal: 


1. Line 94 places the dest-terminal/ input in the OMA header. 


2. Line 95 specifies the length of the output message, including four bytes for the TEXT- 
LENGTH and AUXILIARY-DEVICE-ID fields. 


3. Line 97 sets the AUXILIARY-FUNCTION field of the OMA header to the value (X‘C9’) 
that directs IMS 90 to queue the output message as input for the destination terminal 
(3.10.2). 


4. Line 99 transmits the explicit output message to the destination terminal via the 
SEND function. 


If there are no errors encountered by IMS 90 in executing the SEND function, the operator 
of the originating terminal receives a message indicating that the print transaction has 
been successfully queued at the destination terminal: 





1. Lines 101 and 102 provide the text of the message output for the originating 
operator. 


2. Line 106 sets the DESTINATION-TERMINAL-ID field of the OMA header to binary O 
and thus ensures that this message is output at the originating terminal (assumed to 
be a UNISCOPE device). 


3. Line 107 ensures that this message is output on the UNISCOPE screen instead of on 
the COP. 


BEGIN1 terminates normally, without succession. The originating terminal is now free for 
other interactive use. 


On the other hand, if IMS 90 encounters an error in queueing the message output by 
BEGIN1 as input to the destination terminal, the ERROR-PROC procedure formats an error 
message for output to the originating operator, and BEGIN1 terminates normally (lines 100 
and 110-115). The output message is dequeued. The operator, depending on the nature of 
the error, may reenter the original input message. 


Although the text of the message output to the originating terminal on successful return 

from the SEND function (line 102) states that the transaction has begun at the destination 

terminal, this may not be true. All that has actually occurred is that the output message 

has been successfully queued as input from the destination terminal. If the transaction . 
code it contains is invalid, however, or some other error intervenes, the print transaction ® 
does not begin. Such occurrences are not reported to the originating action program by 

IMS 90, but to the destination terminal. 
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00004 IDENTIFICATION DIVISION. 

00002 PROGRAN-ID. BEGGING. 

00003 ENVIRONMENT DIVISION. 

00004 CONFIGURATICIN SECTION, 

OO00S SOUKME-COMPUTER. UNTVAC-OS3. 

06006 OUBJECT-COMPUTER. UnlVAC-OS3. 

00007 DATA DIVISION. 

00008 WORKING-STORAGE SECTION. 

00009 O04 DICe-SEu., 

060040 O2 DICE-CODE PIC x VALUE ='7 40°. 
00044 O2¢ FUNC-CODE PIC x VALUE ='O4’. 
00042 O2 Y-COORD PIC X VALUE =’°OC’, 
00043 OZ x-COORD PIC x VALUE =’0O0’. 
60044 LINKAGE SECTION. 

00045 04 PROGRAN-INFURRATION-BLOCK. COFY PI674. 

00016 O02 STATUS-CODE PIC 9C€4) CormP-4. 
00047 O2 DETAILED-STATUS-CODE PIC 9(4) COmP-4. 
06048 O2 RECORD-TYPE REDEF INES DETAILED-STATUS-CODE. 

00047 O3 PREDICTED-RECORD-TYPE PIC xX. 

00020 O3 DELIVERED-RECURD-TYPE PIC X. 

0002 4 OZ SuUCCESSOR-ID PIC xté6}. 

00022 O2 TERMINATICON-INDICATOR PIC X. 

000253 O02 LUOCK-ROLLBACK-INDICATOR PIC xX. 

00024 O02 TRANSACTION-ID. 

00025 O03 YEAR PIC 9C€4) COrmP-4. 
96026 G3 TODAY PIC 9(€4) Conmp-4, 
00027 O03 HR-MIN-SEU Pic 9t9) CORF-4. 
00028 OZ DATA-DEF-REC-NAHE PIt AC 43 

00027 O2 DEF INED-FILE-NAME PIC xt7}. 

06030 O2 STANDARD-NSG-LINE-LENGTH PIC 904) COMmP-4., 
00034 O02 STANDARD-MNSG-NUMBER-LINES PIC 9(4) COrP-4. 
—6 00032 OZ WOURK-AREA-LENGTH PIC 9€4) COHP-4. 
00033 O2 CONTINUITY-DATA-INPUT-LENGTH FIC 904) COMmP-4. 
00034 O2 CUNTINUILTY-DATA-GUTPUT-LENGTH PIC 9(€4) COMP-4. 
O0035 O2 WORK-AREA-INC PIC 704) Conp-4. 
90036 O2 CUNTINUITY-BDATA-AREA-INC PIC 9€4) COMP-4. 
00037 O02 SuUCCESS-UNIT-I0. 

00038 O3 TRANSACTION-DATE. 

00039 04 YEAR PIC 99. 

00040 O4 PUNTH PIC 99, 

0004 4 O4 TUCAY PIC 99, 

00042 O3 TIME-CF-DaY. 

00043 O04 HIUR FiC 9. 

00044 O4 MINUTE PIC 99. 

00045 04 SECOURD PIC 99, 

00046 O3 UNIQUE-SLIFF IX PIC 999. 

00047 O2 SOURCE-TERRINAL-CHARS. 

90048 O3 SOURCE-TERMINAL-TYPE PIC X. 

00049 O3 SOURCE-TERMINAL-MSG-LINE-LENGTH PIC 9(43 COMP-4. 
00050 O3 SOURCE-TERNINAL-NSG-NUABER-LINES PIC 904) COMP-4. 
00054 O04 INPUT-RESSAGE-AREA. CORY IRA/4. 

000S2 O2 SOURCE-TERNIRAL-1D PIC x(4). 

60083 O02 DATE-TIME-STAMF. 

00054 O3 YEAR PIC 9043 COMP-4. 
00055 03 TODAY PIC .9€43 CuomP-4. 
OG056 O3 HR-AIN-SEC PIC ¥(C9) COrMP-4. 
00057 O2 TEXT-LENGTH PIC 9(4) COMmF-4. 
v0058 O2 AUXILTIARY-~pDEV-ID. 

QOO0SY O3 FILLER PIC x. 

00060 U3 ALIX-DEYV-NO PIC X. 

00064 OZ TRANS-COBE PIC xtsi. 

06062 OZ FILLER FIC X. 

00063 Of DeSsT-TERN FIC x£41. 


Figure 3—30. Sample COBOL Action Program, Directing Print Transaction at Another Terminal (Part 1 of 2) 
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00064 O2 FILLER PI Xs 
00065 O2 TEXT-~ARESA PIO x23. 
00066 O41 WORK-AREA. 
GOO? O2 Oubhhy PIG xX, 
00063 G4 OQUTFUT-AESSSOGE-AREA. Cory CHa. 
00049 Oc GESTINATION-TERMIAAL-ID PIC x4). 
00070 O2 SFS-CFTIONS PTC xtiei. 
OOO7 4 OZ FILLER Pit) xC2). 
00072 O2 CUNTINUGUS-OUTFUT-CODE PIC xo49. 
OGO73 Of TEXT-LERGTH PIC 9043 COmP-4. 
00074 Of AUXILIARY-DEVICE-Ic. 
00075 OS AuUx-FURnRC TION PIC. Xs 
OG076 OS AUZ-DEVICE-RNU PIU Xs 
OOO LF Of SENO-FiSG, 
GOO78 GS GuUTPUT-TexT FIC Xt2?1, 
00074 O3 FILLER PIC xt44), 
Ga080 Of pEGIN-MSG REDEF INS se Wo-M56. 
COO 4 O3 CURSGR— 4 PIC et4), 
Ogc0s2 O03 786-4 PIC xX€30). 
BOOS O3 TERM -NANE PIC kt4ad., 
GOOUS4 O3 FILLER eee xCSJ. 
OOdss O2 ERRGR-OSG REDEFIVES SeNO-fAsh. 
OUOGS OS CURSOR-Z Fit xi4i). 
COO87 O3 FisG-Z2 Pit FL335% 
GOU8S O3 ERRGRK-COOE Pieper 
Oodss PROCEGURE OIVISIOn USied Fe RUGRAM- INF ORRATION-B LOCH 
GOGO INPUT-TESSAGE-AREA 
Oa? 4 WOR RARE 
OOO? CHITPUT AME SSaGE-SRE A, 
Oones 3s MOVE-MESSAGE. 
OOO AVE DEST-TERM To DESTINATION-TERNInNAL-LO. 
OGOFS SUBTRACT 44 FROG TEXT-LENGTH [nN INPLIT-MESS4G5E-ARECA 
OOOSS GIVING TEXT-LENGTH IN ULITPUT-AESSeGE-AREA 
OOO MOVE 'T’ Tua AuUA-FURITION. 
guages MOVE TEXT-AREA TO GUTPUT-TERX?]. 
O00oY CALI ‘SEND’ USING GQ“UTPUT-NESS&GbE-AREA. 
OO 4G0 IF STATUS-CODE NOT EQUAL TG & GO TO ERROR-FRUC. 
OO 404 MOVE QICE-Seu Tu CuRSoR—4. 
00402 MOVE “TRANSACTION BEGUN AT TERMINAL ° TO ASG-4 
OQ403 MOVE DEST-TERM To TERM-NAKE. 
OG 104 MOVE 42 TO TEXT-LENGTH IN QUTFUT-AESSAGE-AREA 
00405 TERRMINATE-ROUTINE. 
OG4AGS MOVE LOUW-VaLUES TO CESTINATION-TERMINAL-ID. 
OO 407 MOVE LOW-YALUE TU AUX-FUNE TION. 
00408 mOVE (AN? TO TERMIRATION-IROGICATOR. 
OO409 CALL ’RETURN’., 
O0440 ERRUR-PRQC. 
00444 Move OLCE-SEG Ta CuRSUOR-2. 
00442 MOVE ‘TRANSACTION NOT BEGUN BUE TO ERROR ° TO mS6-2. 
00443 MOVE DETAILED-STATUS-CODE TO ERROR-CODE. 
00444 mOVE 47 Tad TEXT-LENGTH IN GUTPUT-RMESSAGE-AREA. 
00445 GO TO TERMINATE-ROUTINE. 


Figure 3—30. Sample COBOL Action Program, Directing Print Transaction at Another Terminal (Part 2 of 2) 


3.15.5. Sample COBOL Program Using Screen Format Services 


Figure 3-31 is a compiler listing of the action program, JAMENU. This program is the first 
in a series of programs that make up an entitlement accounting system. JAMENU 
processes a password entered as input from the terminal. If the input is valid, JAMENU 
displays a menu screen. If the input isn’t valid, JAMENU displays an error screen and 
terminates. 
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© Remember, before using screen formats in your action program, you must: 
= create the screen formats and store them in the screen format file (SYS$FMT) 
# specify the SFS=n parameter in the OPTIONS section of the configuration 


= specify OFT=-+n in the IMS start-up job stream 


OOD001 IDENTIFICATION DIVISION.» 


e* e@¢e¢@e@h6Um@t@tmhUCUchmhCrNWhCUC HOhUCUCU HhUhhUC HhU hh 


900002 
030003 PROGRAM-ID. JAMENUe 
ODOOCN*RE MARKS» PROCESS SIGNON #¢ MENU. 
C000 05 € = an a a a a rn a nn rn rr rn nn ore en  ieatenateteseiertetae 
O00006* THIS PROGRAM PROCESSES THE SIGNON AND SYSTEM/80 MENU 
oooo07« SCREEN FOR THE ENTITLEMENT ACCOUNTING SYSTEM. 
oooo0ss IF THE SIGNON IS FOUND TO BE VALID, THE MENU WILL BE 
oop0c09* DISPLAYED. OTHERWISE, THE ERROR OVERLAY SCREEN WILL BE 
oogo0l0* DISPLAYED AND THE TRANSACTION TERMINATED. 
000011 *#-- ---~----~+-- --- = - - - + +--+ - + wen ee ee etaaeettetetod 
0390012 
ODOOI1S ENVIRONMENT DIVISION. 
ooo0014 
O0001S CONFIGURATION SECTION. 
000016 SOURCE-COMPUTER. UNIVAC-OS3. 
000017 OBVECT-COMPUTER. UNIVAC-OS3-6 

@ 000016 
000019 DATA DIVISION. 
O00U2u 
000021 WORKING-STORAGE SECTION. 
000022 77 CUST-FILENAME PIC X(¢(7) VALUE *CUSTMST®. 
030023 77 SCTL-FILENAME PIC X¢€7) VALUE *SYSCTL®*. 
000024 
000025 01 SCREEN-FORMAT-IDS. 
000026 OS SF-MENU PIC xt8? VALUE *JASMENU * 
000027 05 SF-a0D} PIC X¢8) WALUE *“JASADDI * 
000026 OS SF-A0D2 PIC X€8) VALUE *JASADD2 * 
000029 0S SF-A0D3 PIC X(8) VALUE *JASADD3 * 
0000303 GS SF-CH6} PIC xX€8) VALUE *JASCHG] * 
000031 0S SF-CHG2 PIC X(8} VALUE °JASCHG2 * 
000032 0S SF-CHG3 PIC xX(8) VALUE *JASCHG3 * 
0090033 O5 SF-DELI PIC X¢8) VALUE *JASDEL] ° 
9090034 OS SF-O1S1 PIC Xt8) VALUE *JASDIS] °* 
000335 05 SF-LSTl PIC X€8) VALUE *°JASLSTI * 
000036 0S SF-WAR] PIC X(8) VALUE “*JASWAR] ° 
900037 05 SF-ERR1 PIC X¢8) VALUE *“JASERR °* 
990038 O05 SF-TERM PIC x8) VALUE *JASTERM * 
02300939 
990090 01 VALID-SUCCESSOR-IDS. 
090041 OS MENU PIC X¢6) VALUE *JAMENU*S. 
ooo004s: 05 CuUST-aDD PIC X(6) VALUE *JAADDI1*. 
0390043 05 CUS T-CHG-i PIC X€6) VALUE *JACHG1*. 
900044 05 CUST-CHG-2z PIC Xt6) VALUE *JACHG2*. 
990045 05 CUST-CHG-3 PIC X(6) | VALUE *JACHG3°. 
090046 05 CUST-DEL PIC X¢6) VALUE *JADELI*. 
Oo00S7 O05 CUST-DISPLAY PIC X(6) VALUE *JADIS1°. 
000046 0S CUST-LIST PIC xX(6) VALUE °JALSTI°. 





Figure 3—31. Sample COBOL Program Using Screen Formats (Part 1 of 8) 





Figure 3—31. 








Sample COBOL Program Using Screen Formats (Part 2 of 8) 
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OO00049 0S w#S-ACTIVITY PIC Xt6?) VALUE * JAWARI*% © 
00095b 
930051 G1 wWS-TABLES-. 
00005< 0S MENU-TABLE. 
000053 10 FIUILLER PIC X@€9) VALUE °UIVJAADOII®. 
000054 10 FILLER PiC X€9} VALUE *O2JACHGII*,. 
000055 190 FILLER PIC X€9)} VALUE *O3¥ACHG2I*. 
000056 10 FILLER PIC X€9) VALUE *OSJACHGSI°%. 
oo900S7 19 FILLER PIC X€9) VALUE *USJADELII®. 
090058 10. FILLER PIC x€9) VALUE °O6JADISII*%e 
oo00s9 10 FILLER PIC X€9) VALUE *O7JALSTII*% « 
s0006U 10 FILLER PIC X¢€9) VALUE *OBJAWARII*« 
9900063 10 FILLER PIC X09) VALUE *O9JAMENUN®,. 
000062 10 FILLER PIC X49) VALUE *1OJAMENUI®. 
0000653 
Oog0064 05 MENU-TBL REDEFINES MENU-TABLE OCCURS 10 TIMES 
000065 INDEXED BY MENU-INDX. 
0390066 10 MENU-SEL PIC 9C2)- 
O00067 10 MENU-NAME PIC X6)-6 
000066 16 MENU-IND PIC X. 
000069 
OOOO TO eee ee EEEEERKEE EEE EKEREEREREREERRERERERE RES SEKESKEKE SRESESE 
COOO7T1*® THIS IS THE ERR PROCESSING TABLE FOR RETRIEVING ERR 
Q00072* MESSAGES FROM THE SYSTEM CONTROL FILE FOR DISPLAY 
OOOOT3S* #wWITH THE OVERLAY. 
ODDO TH RES EKEREEEREEECEEREE KE EKAREE ERK ESERE REAR AEHE SEKAERESEE EEE SEES 
000075 GOS ERR-STATUS-TABLE- 
930976 19 FILLER PIC x¢€40}) 
o000T7 VALUE *01090212031304149051506160717080109021020%. 
900076 
coooT9s OS ERR-TFABLE REDEFINES ERR-STATUS-TABLE OCCURS 10 TIMES 
000086 INDEXED BY ERR-INDXe 
030081 10 ERR-CODE PIC 99.6 
900082 10 ERR-KEY PIC XX- 
yp0083 05 NO-ERR PIC 99 VALUE 256 
0000847 
990085 LINKAGE SECTION. 
COOOS6 Gil PROGRAM-INFORMATION-BLOCK. COPY PIB. 
g00087 
990088 O1 INPUT-MESSAGE-AREA. COPY IMA. 
500089 OS IMA-PASS~-1. 
090090 1G IMA-DICE PIC X@4). 
0090091 10 IMA-~SIGNON PIC XO5d)6¢ 
000092 10 IMA-PASSWHRD PIC X¢€4). 
900093 OS IMA-SCREEN-REC REDEFINES IMA-PASS-1le 
000094 10 SR-CUSF-NBR PIC 96). 
030095 10 SR-MENU PIC 99. 
000G%$6 10 SR-TFRSMIT PIC Xe 
o00097 10 FILLER PIC X44}. 
0090098 Gl wWORK-AREA. 
000099 J5 IMS -PARAMETER-LIST. 
090190 1} £MS-FILENAME PIC X@7).- 
209101 10 AMS~-RECORO-AREA PIC X¢zc56}).- 
000152 10 i™MS-KEY PIC X€14). 
930103 1G = 4MS-FILE-POSITION PIC Xe 
C30104 10 iIMS-ALGN COMP~-4 SYNC. 
00105 IC iMS-SCREEN-ID PIC X€8)- 
090106 1G SCREEN-SIZE PIC 9¢4) COMP SYNC. 
090107 JS wA-CUNTROL-KEY. 
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99019% 10 CNTL1 PIC X€2}. 

CQIO109 190) «6CNFTL2-3 PIC X¢€4). 

990116 10 CNTL23 RECEFINES CNIL2-3-6 

999111 iS) OCNTL2 PIC 92). 

No0312 1S CNTL3 PIC X€2). 

900113 U5 ERR-STATUS PIC 59. 

9930114 OS REFORMAT-DATE. 

030115 10 P-MONTH PIC 99. 

330116 19 P-DAY PIC 99, 

"90117 13 P-YEAR PIC GS, 

COOL1b US ERR-FLAG PIC X. 

9390119 88 ERR VALUE *37% *28 #3* *ye%, 

939126 68 osEL-ERR VALUE °2°*, 

99012] 8B bBLD-ERR VALUE *3*, 

990122 338 PASSWRU-ERK VALUE °4*, 

£00123 US SCREEN-RECORD. 

9360124 1O 8 SR-DATE PIC 96). 

339125 10) yR-TIME PIC 96). 

790126 05 SR-ERR-TEXT PIC X(50). 

990127 5 Sb-STAT PIe X€5)-6 

900126 G5 PASS WRD-REC.e 

900129 10 FILLER PIC XZ)- 

0301230 13 PASSH#RD PIC xX€4). 

990131 13 PASSWROD-SEL PIC X€25)-6 

SIU132 JC PASSWRO-MENU-SEL REDEFINES PASSWRD-SEL 

999133 PIC X OCCURS 25 TIMES INDEXEU BY PASSWRD-INDX. 

030134 10 FILLER PIC X€33)- 

C30135/ 

9390136 J5 CUST-RECORD. COPY CUSTMST. 

030137 

0001338 65 SCTL-RECURD. COPY SYSCTIL-. 

N90139 

930140 

COO01%1 Cl OUTPUT-MESSAGE-AREA. COPY OMA, 

090142 O§ OMA-TEXT PIC X(3900).- 

999143 

CJOlY4 C1 CONTINUIFY-DATA-AREA. 

90145 0S CDA-PASSWRD PIC Xt4). 

900146 35 CDA-MENU-SEL PIC X(25). 

N90147 95 CDA-PASSWRO-HENU-SEL REOEFINES CDA-MENU-SEL 

C5914 PIC xX OCCURS 25 TIMES. 

090149 OS CDA-CUST-KEY. 

990150 10 CDOA-CUST-NBR PIC 9tO?. 

990151 G5 COA-ACCT-CODE PIC X€4). 

000152 35 PASS-FLAG PIC Xe 

030153 88 PASS-THRU. VALUE "1°"*2 ¢eze eH eK ©, 

930154 EB PASS] VALUE "1%. 

990155 EB PASS2 VALUE "2%, 

030156 68 PASS3 VALUE °3°*, 

CJ0157 88 PASS4 VALUE *4*, 

990155 68 PASSS VALUE *S*. 

990159 05 COA-STATUS-BYTE PIC ¢. 

000160 05 CDA-PROGRAM-NA ME PIC X€6)-6 

CJO161/ 

900162 PROCEDURE DIVISION USING PROGRAM-iNFORMATION-BLOCK 

000163 INPUT-MESSAGE-AREA 

9901648 WORKK-AREA 

NO00165 OUTPUT-MESSAGE-AREA 
© 000166 CONTINUI TY-DATA~AREA 


Figure 3—31. Sample COBOL Program Using Screen Formats (Part 3 of 8) 
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OGO167 MAIN-LOOP SECTION.) 
DAFT LC SESH SHS SSeSeSHFSHSEHESHEHHEHHEHHHEHEHESHEESSHEHHSSEHFSEHCHEHHFESHESCHEEEHHCEOEH 
THE PASS FiaAG IN THIS SECTION TELLS THe PROGRAM AT WHICH 
POINT IMS HAS RETURNED CONTROL OF THE PROCESSING TO FHE 
PROGRAM, A PASS 2 FLAG MEANS THE PROGRAM HAS ALREADY PUT 

OUT THE SCREEN AND IS NOW READY TO ACCEPT THE DATA FROM 


O90169* 
DO017yU* 
SO0i71* 
0001 7T2* 
O030173+% 
3IJIIT4* 


900177 
030178 
939179 
330185 
930181 
990182 
000183 
330184 
090185 
030186 


THAT SCREEN TO PROCESS. 


OTHERWISE THE PROGRAM WANTS FO 


DO THE INIVIAL PROCESSING TO PUT OUT A SCREEN. 


DO OL TOK EH SHES eee S HEE HFEEE HE FEE EES HEEF HERE REE EEEFE FEF HEESE HEED SEED 
COOlT6 JCO-BEoIN. 


IF NOT PASS2 


PERFORM LOO-INITIALIZE 


4F NOT ERR 


PERFORM 200-BUILD-SCREEN 


cLSé 


PERFORM S0G~-ERR-MESSAGE 


ELSE 


PERFORM 25U0-READ-SCREEN. 


PERFORM SO7-RE TURN. 


3~140d 
Update A 





PIOL SI TESS SHS See HSS HHH HEHEHE EEFESEEHE HES HEHEHE AEFE PEL ESEEESEFE CED E BS 
INITAALIZATION OF FIELUS AND FLAGS IS VONE HERE. 

ALSO CHEZKING IS OONE TO SEE IF THE PROGRAM ENTERED 
FROM A SIGN ON OR WAS CALLED FROM ANOTHER PROGRAM, 

ONLY IF ENTER FROM A SIGN ON DOES THE PROGRABK REFRIEVE 
THE PASSWORD RECORDe GIRER WISE IT IS CARRI£D TO CHECK 
VALIDITY OF MENU SELECTION, 
FIDL SY HAH SASS HEHEHE FEFEH SHEE FES FHF SHE HFHEHAEESEHHHPEHHEHFHESEHEHHEHE HORE HE 
NIOI9S IOv-LVLIIALIZE. 


050188* 
090189% 
030190 
O9230191*% 
Q3J0192% 
0391935% 


030196 
JIO197 
030196 
939199 
JO02CU 
JO92C]1 
JOGO202 
9902C3 
N90204 
Jobe ce 
~ G02 26 
COU0Lo7 
I902C& 
IIOLZUY 
JIO? Iu 
950211 
JOO2 le 
2u0213 
O90214 
CQ0213 
30216 


MOVE SPACE 


TO IMS-KEY 
IMS-F ILENAME 
SR-ERR-TEXAT. 


MOVE °2* TO PASS-FLAG. 
MOVE *°O°* TO ERR-FLAG. 
MOVE CURR P~TRANSACTION-DATE TO REFORMAT-DATE « 
TF CDA-PROGRAM-NAME FCOQUAL LOW-VALUCS 
MOVE IMA-PASSW&RD ¥O CNIL2-3 
MOVE ‘*PwW® TO CNTL1 
MOwE SPACE TO IMS-RECORD-AREA 
MOVE SCTL-FILENAME TO IMS-F ILENAME 
MOVE WA-CONTROL-KEY TO IMS-KEY 
PERFORM SOc -bLT 
JF ERR 
MOVE *4® TO ERR-FLAG 
ELSE 
MOVE IMS-RECORD-AREA 0 PASSWRO-REC 
MOVE PASSWRO-ScL TO COUA-MENU-SEL 
MGVE PASSWRD TO COA-PASSWRD. 


MOVE MENU 


TO CDA-PROGRAM-NAME. 


FIB?]S] LSA SHH HSSHEEEHEHEEFHE SHE EHH EEH HEHE HEP HEHEHE E SHEE HEERE HEHEHE HHH EES 


T4E MAIN PROCESSING AMY BUILDING CF THe SCREE™ DATA IS 


JZJOZ ls 
JIUC1G* 


IN HERE. 


DONE 


DSO CUEK SARAH E HEHEHE FERRE FE HHH HHS HEPHPHEFHAAHEEEAEH HEP HEEFFETERHFOR OTe 
CJ0221 2UO-BUAILL-SCREEN. 


53922 

239223 
9290224 
anipags 


MOVE LMA-SOURCE-TFERMINAL-1ID 


MOVE SF-MENU 
MOVE ALL *9°* 
MOVE REF URMAT-DATC 


TO IMS-SCRLEN-iDe 
FO SCREEN-RECORD. 
TO SR-DATE. 


Figure 3—31. Sample COBOL Program Using Screen Formats (Part 4 of 8) 


TO OMA-DESTINATION-TERM-ID.- 
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O33226 MOVE PHLive=oF <DAY TO SR-TIME. 

OIO227 MOWE le TO SCREEN-SIZE 

7O9226 PERFORM 5°5-3UiL0. 

NOU 29 IF ERR 

JI02 Fo PERFORM QSCO-ERR-MESSADBE. 

9902 31 MOVE MENU FO PIS-SUCCESSOR-ID. 
099272 MOVE *%E* TO PIB-TERMINATION-IND. 
W302 33 


DS FYE SAFES EF SEER EHEE HEHEHE EHEHREFSHEESEEHHRESHEHEEHHHEHAEHPETESHFEHEHS HEHE EHES 


CJUC3S* THE MENU ScLECTIGN VALIDITY 1S CHECKED HERE 
TODS FOKSE FHSS HSA SHAH AS ES HD HEHEHE SESH HE PHEHHEHA HEHEHE AHHH ESHEHHEDE HS 


OO0U237 ZSU-RKEAD-SCRLEN. 


P992 36 IF CDA-PASSWRD-MENL-SEL (SR-MENUD NOT CQUAL FO °%1* 
330239 MOVE *2* TO ERR-FLAG. 
CjJOL24S iF ERR 

JvG2 41 PERFORM FUCH-ERR-MESSAGE 

IO9024e2 ELSE 

[20243 PERFORM 26€C-SEI-MENU, 

830294 


DAIFDZES RSH SSS SESE HHSFHSHEFHEEFHEHFEAAFHAHHHEPHEFHEFHHSEHHEHEHEHHAHETELE BEES 
CIJO24o* IF MENU SELCCTION IS VALID CONTROL 1S SET FOR NEXT STAGE. 
AGU LY TE SH AESHEHSHEHFSHEHESPEHH EH HEHHHESHEHEHSHEHEHEHHEHEEHCHE HHH EHPEPH HE ES 
[9924s 260-SEI-MENU. 


C9049 MOVE MENU-NAME (SR-MENU)D TO PIB-SUCCESSOR-ID. 
739925u MOVE MENU-IND (OSR-MENUD TO PIB-TERMINATION-IND. 
390251 MOVE SR-CUST-N3BR TO CDA-CUST-NBR.e 


JII’ZSe MOVE *O* TO PASS~FLAG. 


590¢53 IF SR-MENU = 9G 
Ca0254 PERFORM 270-LOGOFF. 
800255 *% 


DD SSL ESHER EEE EEE ERE SER HEEEEEEE TERE AHEREHEETEE HEE EEHEEEEDEEEEEEEDG 


OO002S57* sULLD TERMINATION SCREEN 
DIO ZS AHHH SHS SSSEHHESDHESTESHHHEHERSESTSSEHEEESSEHEEESESH SHEETS E SHEDS 


030259 270-.0GOFF. 


990260 MOVE IMA-SOURCE-TERMINAL-IL TO OMA-DELSTINATION-TERM-ID. 
000261 MOVE SF-TERM™ TO IMS-SCREEN-ID.e 
800262 MOVE ALL *O* TO SCREEN-RECORD. 
O00263 MOVE CORR P-TRANSACTION-DATE TO REFORMAT-DATE. 
030264 MOVE REFORMAT-DATE TO SR-DATE. 
030265 MOVE P-TIME-OF-DAY TO SR-TIME. 
000266 MOVE 12 TO SCREEN-SIZE. 
000267 PERFORM SCS5S-BUILD. 

O00268/ 

900269 IMS-CALLS SECTION. 

990270 

IB027T1 SOO-SETLe 

DO00272 CALL *SETL* USING IMS-FILE NAME 
090273 IMS-FILE -POSITION. 
O30Z27T4 SOO-EXIT. 

9090275 EXIT. 

890276 

OQIA2TI SBVI-ESETL- 

0002 7b CALL “SESETL® USING IMS-FILENAME. 
O99<¢c79 AF PEFSB-STATUS-CODE 1S GREATER THAN uo 

e3028uU MOVE *1° ¥CO ERR-FLAG.e 

OCIC281 SOI-EXIT. 

C0282 EX1Te 

000283 

O30284 SO2-GET. 


Figure 3—31. Sample COBOL Program Using Screen Formats (Part 5 of 8) 
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JG0285 CALL ‘GET® USING IMS-FILENAME 
JJ0286 IMS-RECORD-AREA 
oo0287 IMS~KEY. 
900285 IF PIB-STATUS-CUDE IS GREATER THAN O 
VIO28Y MOVE 1* TO ERR-FLAG. 
JGG290 SU2-EXIT. 
S90¢91 EXIT. 
OVO29e 
S30293 SIS-GETUP. 
OJO294 CALL *GETUP® USING IMS~FILENAME 
VIIL2SS IMS-RECORD-AREA 
990296 IMS-KEY. 
JO0297 iF PIS-STATUS-CODE IS GREATER THAN & 
TOO29s HOVE °1* FO ERR-FLAG. 
JJI2Z99 SLS-EXILTe 
CIO3S0C EXiT. 
JIVUI3O1 
830372 SO4-PUT. 
Secs" Ss CALL “FUT® USING LMS-FILENAME 
JI0504 IMS-RECORD-AREA’ 
Q30305 IF PIB-STATUS-CUDJE IS GREATCR THAN JU 
€00396 MOVE *1* TU ERR-FLAGe 
CQ0307 SO4-EXiTe 
COO0306 EXIT. 
ND0309 


FIO TL UES SHS HS HSHHESEHFESEEHEHHHTHEEHEEHESEHHEHESHOFHEFHESESEHEHREDESOH SES ES 


O3O311e CALL FOR MAIN SCREEN FOR PROGRAM 
ODO FI ZEPESFESEHEFEESES SHED EE HHHESHESESEHHSESEFHSHHEFEFESHESESES FEDS 


090313 SO5-BUILD. 

N30314 CALL *BUILD® USING OUTPUT-MESSAGE-AREA & 
B90315 IMS-SCREEN-ID 
990316 SCREEN~RECORD 
000317 SCREEN-SIZE 
000318 SG-STAT. 
000319 1F PIB-STATUS-CODE IS GREATER THAN O 

030320 MOVE °3° TO ERR-FLAG. 

830321 SOS-cxXIT. 

990322 EXiT. 

900323 


AIO TSZYECAHSEHSSSHESESHSHESHHSEHSFHREFGEHEFSHEHFEFEHHESHEHSEEHEECEPESCESEFEOCHESCESCSE 


0390325 CALL FOR ERR OVERLAY SCREEN 
OCOD ZS ZEKSFTSHSSHSASPSFHEHHEHE SH SSEEHHEEEHHSEHHEEHHEHPEEHGEHESHESESEECHEHOSOESS 


N00327 SOS-BUILD-ERR. 


900328 CALL *BUILD* USING OUTPUT-MESSAGE-AREA 
000329 IMS-SCREEN-10 
830336 SR-ERR-TEXT 
090331 SCREEN-SIZE 
CO0332 SE-STAT. 

000333 IF PIB-STATUS-CODE IS GREATER THAN O 

IJO334 MOVE *°3* TO ERR-FLAG. 

030335 SOS-BLD-ERR-EXIT. 

CO0336 EXIT. 

000337 

000338 SO6-REBUILD. 

000339 CALL *RESUILD® USING IMS-SCREEN-ID 
0003480 IMS~RECORD-AREA> 


000341 SOG-EXIT. 


000342 EX1T. - 
0003483 r 


Figure 3—31. Sample COBOL Program Using Screen Formats (Part 6 of 8) 
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900344 
090355 
030346 
000347 
000348 
000389 
000350 
000351 
000352 
000353 
000354 
030355 
000356 
000357 
0003556 
000359 
000360 
000361 

000362 
000363/ 
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SO T-RETURN. 
CALL S2IETURN®, 
SC T-EXIT. 
EXIT. 
SO8-INSERT, 
CALE °EINSERT® USING IMS-F ILE NAME 
LAS-REGORD-AREA 
IMS-KEY. | 
IF PIB-STATUS-CODE IS GREATER THAN D0 
MOVE °1° TO ERR-FLAG. 
SOS-EXIT. 
EXiTe 
SOS-SNAP. 
MOVE *S°* TO PIB-TERMINATION-INDO. 
CALL *SNAP® USING PROGRAM-INFORMATION-BLOCK CDA-STATUS-BYTE. 
SO99-EXIT. 


EXIT. 


000364 ERROR-PRGCESSING SECTION. 


090365 
030366" 
CI0367*% 
000366*% 
O00369% 
D903 70% 
OO0371* 
000372* 
OO03ST73* 
COO37&s 
000375 
OO003T6 
CIO3ST77 
0003786 
o00379 
000384 
000381 
000382 
000383 
000384 
000385 
0390386 
930387 
030388 
050389 
000396 
C00391 
0903592 
'D0G393 
090394 
000395 
000396 
900397 
0939398 
BDO399 
000460 
9004801 
9090402 


PREECE EEEEDEREELESESEEESHEREHEEFEEEEEEDEAESHHHESEFHEHOFE THOS 
ERR PROCESSING IS DONE HERZ THE TYPE OF ERR IS 
DETERMINED AND A SEARCH OF THE ERR TABLE IS MADE 
THE APPROPRIATE ERR MESSAGE IS RETRIEVED FROM THE 
SYSTEM CONTROL FILE ANDO DISPLAY IT ON THE OVERLAY 
ERR 6 IS ILLEGAL PASS WORD ERR 9 IS ILLEGAL MENU 
SELECTION FOR PASSWORD OTHER ERRS CONFORM TO IMS 


STATUS ERRORS. 
SHSSSHHSHSSHEEHSEFSESSEHESFESHEFHEHHFHHHSSE SHES HEHESEHHFSSHAHHHSPHCHHEHES 
JOO-ERR-MESSAGE « 

MOVE SPACE TO IMS-RECORD-AREA 
IMS-F ILENAME 
IMS-KEYVe 
MOVE SCTL-FILENAME TO IMS-F ILENAME. 
IF PASSWRD-ERR 
MOVE *5°* TO PASS-FLAG6 
MOVE 6 TO ERR-STATUS 
ELSE 
IF SEL-cRR 
MOVE 9 TO ERR-STATUS 
ELSE 
MOVE PIB-STATUS-CODE TO ERR-STATUS. 
MOVE °EM® TO CNTLI- 
MOVE SPACE TO CNIL3. 
SET ERR-1INDX TO le 
SEARCH ERR-TABLE 
AY END 
MOVE NO-ERR TO CNTL2 


BHEN ERR-CODE CERR-INDX) 1S EQUAL TO ERR-STATUS 
MOVE ERR-KEY 4ERR-INDX) TO CNTL2Z. 


MOWE WA-CONTROL-KEY TO IMS-KEY. 
PERFORM S502-GET. 

MOVE IMS-RECORD-AREA TO SCTL-RECORD. 
MOVE ALL *O* TO SR-ERR-TEXT,. 

MOVE SCERR-TEXT TO SR-ERR-TEXT. 
MOVE SF-ERR1 | TO IMS-SCREEN-ID.- 
MOVE 50 TO SCREEN-SIZE. 


Figure 3—31. Sample COBOL Program Using Screen Formats (Part 7 of 8) 
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0004803 MOVE IMA-SOURCE-TERMINAL-ID OMA-DLSTINATION-TERM-ID-) 
000404 PERFORM SOS-BUILD-ERR.- 

0004805 IF PASSS 

bo0s06 MOVE MENU PIB-SUCCESSOR- ID 

000807 MOVE *N® PIB~-TERMINATION-IND 


DOO4&0s ELSE 

BVOCs MOVE MENU PIBb-SUCCESSOR-10 
090410 MOVE °E® O PIB-TERMINATION-IND 
COO4l] MOVE *O* PASS-FLAG. 





Figure 3—31. Sample COBOL Program Using Screen Formats (Part 8 of 8) 


The following discussion of the JAMENU action program assumes that you have already 
created a menu screen format called JASMENU and filed it on the $SYSFMT screen format 
file. 


Begin executing the JAMENU program by entering the transaction code, MENU, followed 
by the password. This is considered the sign-on or first pass through JAMENU. 


MENUICP58 


Transaction Password rd 


Code (5 bytes) (4 bytes) 





JAMENU uses two files (lines 22 and 23): 


1. CUSTMST file 
2. SYSCTL file 


The CUSTMST file contains customer information. The SYSCTL file contains four types of 
records: 


1. account access records (AA) 
2. branch records (BR) 
3. error message text records (EM) 
4. password records (PW) 
Each type record is identified by a 2-byte control key field. (See lines 108-112 and 130.) 


JAMENU accesses the SYSCTL file to validate passwords and retrieve error messages for a 
display on the error message screen. © 
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JAMENU performs five types of routines. It: 

1. validates passwords 

2. builds menu screen 

3. validates menu selections 

4. builds error screen 

5. builds termination screen 
On the first pass, JAMENU accesses the SYSCTL file to validate the password entered at 
the terminal. lf the password is valid, JAMENU saves all data pertinent to that password in 


the continuity data area (line 211-216), builds the menu screen (lines 221-232), and 
terminates in external succession to itself (JAMENU). Menu screen JASMENU follows. 

















86/23/81 96:49:28 JASMENU 82/89/81 





ENTITLEMENT ACCOUNTING SYSTEM 


SELECT ONE (1) OF THE FOLLOWING OPTIONS: 

1. ADD A NEW CUSTOMER RECORD. 
“2. UPDATE CUSTOMER NAME/ADDRESS INFORMATION. 
*3. UPDATE BRANCH CUSTOMER INFORMATION. 
“4. UPDATE CUSTOMER ENTITLEMENTS. 
*5. DELETE A CUSTOMER RECORD. 
“6. DISPLAY CUSTOMER INFORMATION. 
7. LIST ALL ACCOUNTS (ON THE WORKSTATION). 
8. ENTER WORKSTATION ACTIVITY RECORDS. 
9. LOGOFF SYSTEM. 

































“ENTER CUSTOMER NUMBER 
MENU SELECTION: 
PLACE CURSOR HERE TO TRANSMIT 





[_] 


In the menu screen build routine (lines 221-232), the BUILD function call that actually 
calls the menu screen identifies the buffer address where IMS receives the screen format 
as the output message area (line 314); the format name as IMS-SCREEN-ID (line 315, 
defined line 105); the variable data as SCREEN-RECORD (line 316, defined lines 123-125): 
the data size as SCREEN-SIZE (line 317, defined on line 106); and, the output status as 
SG-STAT (line 318, defined on line 127). 


Notice, all the parameters you specify on the BUILD function must be defined in t'.e work 
_ area. 
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lf the BUILD function is unsuccessful, an error code 3 is moved to the ERR-FLAG (lines 
118 and 121) indicating a build error. 


lf the password is invalid on the first pass, JAMENU accesses the SYSCTL file via the EM record 
key for the error message record (lines 380-388), searches an error table to find the appropriate 
error message (lines 390-395), retrieves that error message (lines 396-398), builds the error 
message screen (lines 399-404), and terminates in external succession to itself (lines 408- 
411). The password error screen follows: 


PASSWORD IS INVALID. ENTER AGAIN. 





On the second pass through JAMENU, the program tests the menu selection made, seeing if it 
is accessible to the password specified in the first pass. If the menu selection is valid for that 
password, JAMENU performs 260-SET-MENU (lines 248-255). This moves to the successor-id 
the correct program name to process the menu selection and an | to the termination-indicator. If 
the menu selection was invalid, JAMENU moves the 2 indicating selection error to ERR-FLAG, 
builds the error message screen (lines 375-411), and succeeds externally to itself. 


lf the menu selection (customer number where applicable and menu number) was valid, 
JAMENU executes another short routine (260-SET-MENU, lines 248-254) that passes control 
to the appropriate action program to process the menu selection. This routine also checks for a 
logoff menu selection (9) that builds the termination screen. Successor programs selected from 
the menu perform file operations required. When processing is complete, control returns to the 
JAMENU program via immediate internal succession and the terminal operator again receives 
the menu screen to enter another selection. 


g i 
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@ 3.16. SAMPLE RPG !I ACTION PROGRAMS 


The two RPG Il action program examples described in this discussion implement a dialog 
inquiry transaction with external succession and use all the IMS 90 interface areas (IMA, 
PIB, OMA, and CDA). RPG II action programs do not use the work area. For an example of 
an RPG Il action program that implements a simple transaction structure with only the 
IMA and OMA IMS 90 interface areas and the entire procedure for getting the action 
program online, see Appendix C. 


The RPG Il action programs in Figures 3-32 through 3-39 reference the same user files 
(STATE and CITY files) as the preceding COBOL action program examples (ACT1 and 
ACT2). The STATE file contains a record for each state; each state record contains the 
state name, state population, and capital city name. The CITY file contains a record for 
each city; each city record contains the city name, city population, and state name. 


To activate the transaction, the UNISCOPE 100 operator enters the transaction code S and 
the name of a state. If the requested state record exists, the RPG II action program (ACT1) 
places the state name, population, and capital name in the OMA with the output message 
heading and control characters. Figure 3-24 shows the results at the UNISCOPE 100. 


ACT1 saves the name of the capital city in the continuity data area (CDA). When ACT1 

designates ACT2 as its external successor and moves the program-id (ACT2) and 

termination code E to the PIB, the capital city name is automatically passed to the 
@ Successor action program, which retrieves capital population from the CITY file. 


Following the display of requested information, the output message CAPITAL-POP? >NO 
YES (described in the OMA) allows the user to request either the capital city population by 
pressing the TAB and then TRANSMIT keys or a termination of the transaction by pressing 
only the TRANSMIT key. 


Figure 3-24 shows the results when the capital city population is requested. The second 
action program (ACT2) obtains the CITY record for the capital city named in the CDA, 
builds an output message containing the capital population, and then terminates normally. 
Figure 3-25 shows the results when termination of the transaction is requested; i.e., no 
capital city population is requested (NQ). 


3.16.1. ACT1 Discussion 


Figures 3-32 through 3-35 illustrate the RPG Il specifications forms required to code 
ACT1, the first of the two action programs needed to provide information about a state 
from the STATE file. A description of each line of coding is provided. 
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RPG II 
SPERRY<>UNIVAC CONTROL CARD AND FILE DESCRIPTION SPECIFICATIONS 


PROGRAM PROGRAMMER OAT te a PAGE a OF ss PAGES 








CONTROL CARD SPECIFICATIONS 


FORMS ALIGNMENT INDICATOR INITIALIZATION 
i a ALTERNATE SUBROUTINE 


ERROA ANALYSIS PRINT COLLATING SIGN HANDLING FILE TRANSLATION 


DuMmP GENERATE SEQUENCE 


DEBUG COE PROGRAM 


NOT USED 
IDENTIFICATION 


OPERATOR 
CONTROL : _ NOT USED 


5 SOB OR BLANK 
©. OR BLANK 
Ss OR BLANK 


NOT USED 
14 


16 





FILE TYPE FILE PROCESSING MODE EXTENSION OR 


FILE DESIGNATION KEY OR RECORD LINE COUNTER CYLINDER OVERFLOW 


CODE 
ADDRESS FIELD LENGTH NUMBER SPACE PERCENTAGE (X10} 
SEQUENCE RECORD ADDRESS TYPE NAME OF OF BYTES NUMBER OF EXTENTS 
FILE FORMAT FILE ORGANIZATION LABEL EXIT Perlis TAPE REWIND OPTION 


OR NAME OF STORAGE 
OVERFLOW SER pevice. | TOBE RESERVED FILE CONDITIONERS 
INDICATOR DEVICE ¥ FOR ISAM 


BLOCK RECORD ROUTINE PROGRAM | 


NGT LENGT KEY FIELO Z 
LENGTH eye a Fae ees CONTINUATION LINES 34 IDENTIFICATION 


LOCATION OPTION 


SNOILVOIIddV 06 SWI 
€/SO IVAINN AdusdS 


NOT USED 


rs 



































Figure 3—32. ACT? Control Card and File Description Specifications Forms 
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Figure 3—33. ACT? Input Format Specifications Form 


RPG Il 
CALCULATION SPECIFICATIONS 


PROGRAMME Poe se DATE PAGE. OF 2 PAGES 


CALCULATION RESULTING 
RESULT FIELD INDICATORS 
ARITHMETIC 


PROGRAM 


COMMENTS IDENTIFICATION 


FACTOR 1 OPERATION FACTOR 2 


LOOKUP 


(FACTOR 2) 1S 


‘DECIMAL POSITIONS 





Figure 3—34. ACT1 Calculation Specifications Form 
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Explanation of Figure 3-32: 
Line Explanation 
1 In column 74, the letter A indicates that this RPG Il program is an action 


program. In columns 75-80, ACT1 is the name of the action program. 


2 The primary input file is one fixed-length record ~- the IMS 90 IMA. 

3 The PIB is specified as an update file. 

4 The OMA is specified as an output file. 

5 The logical file (STATE) is specified as an indexed chained disk file containing 


fixed-length records (4/7 bytes) processed randomly by alphanumeric keys 14 
bytes long beginning in position 1 of the record. 


6 The CDA is specified as an output file and its contents, capital city name 
(CAPITL), are passed to the successor program, ACT2. 


Explanation of Figure 3-33: 
Line Explanation 


7, 8 The IMA contains the state name in positions 19 through 32. The header 
information in positions 1 through 16 of the record Is not referenced nor is the 
transaction code in position 17; however, space must be allotted for them in the 
IMA. Because header information and transaction code fields are not referenced, 
they are not specified on the input format specifications form. This avoids the 
occurrence of a flag for an unreferenced field. The transaction code (S) is 
specified in the TRANSACT section of the IMS 90 configurator and is used at the 
UNISCOPE 100 to load the action program for use in the transaction. 





9-12 The records of the STATE disk file contain the state name (1-14), state 
population (15-22), and state capital (23-47). 


Explanation of Figure 3-33: 


Line Explanation 





13 The state name placed in the IMA is used as the key for the CHAIN operation to 
access the STATE disk file. Indicator 20 is set on if the state name is not found 
in the STATE file. 
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Figure 3—35. ACT? Output Format Specifications Form (Part 1 of 2) 
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PLUS SIGN 



































x 
AND ANO ra ae aR, A J YES <3 EDIT DATE PROGRAM 
= a Al S| aaeerion 2 cat 8 K YES NO FIELD USED IDENTIFICATION 
oO} aly - eee ee L NO VES ZERO 
we O}|2 
a ae 5 C1) oureut 4 D M NO. [NO |] SUPPRESS 
2 2 = of RECORD 
2 2 a fa CONSTANT OR EDIT WORD 
19 20]21 22]23]24}25 |26| 27] 28 39 45 70] 71 











ERROR -. STATE NAS 


\ / 
Gl AM sect tyke St os Sha eee ee dpe 






















sifis Of gs he Pa jee ee) OM eed GARE (eo Sp | [i Joy top ft 


\ / 
se? Es, esi gap ag ok dkok J re 2, 7 AZ £3 i. Beef oe he poe 


\ t 
2 Bah de 7 : ode Tih oi ae Dee la | aE Lt ae | Maes Heid Varn ie) Cael en (Een taut od Cee! ean) Me re) Lees 








i 














| | ft | Soy serone 

















SNOILVOIIddV 06 SWI 
€/SO OIVAINN AdysdS 


A Figure 3—35. ACT? Output Format Specifications Form (Part 2 of 2) 
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Explanation of Figure 3-35: 


Line 





14-31 


32-35 


36-37 


38-40 


3.16.2. 


Explanation 


If the state name is found, it is displayed, as well as the state population and 
capital. Lines 14-25 clear the UNISCOPE 100 screen, set up the header titles, 
and provide for the data requested. After line positioning with DICE output 
function codes (lines 26 and 27), lines 28-31 set up the output message, 
CAPITAL-POP? ANO YES, and set the tab control characters after the message. 
In addition, the program requests the terminal operator to indicate whether the 
capital city population is to be displayed. If capital city population is requested, a 
preformatted answer (YES) is transmitted. This appears in the IMA of the 
successor program (Figure 3-36, line 7 of ACT2) and is compared with the literal 
‘YES’ on the calculation specifications form of ACT2. The hexadecimal values 
shown in this example are ICAM DICE functions or communications control 
characters. (See the fundamentals of ICAM user guide, UP-8194, current 
version.) 


lf the state name is not found, an error message is displayed. These lines. set up 
the DICE control characters and the error message. 


If the state name is found, the capital city name is passed to the successor 
program (ACT2) in the CDA where it is read and used to find capital city 
population from the CITY file. 

If the state name is found, the successor name (ACT2) is moved to the PIB and 
an E is moved into the PIB to indicate external succession. 


ACT2 Discussion 


ACT2 examines the response made by the UNISCOPE 100 terminal operator. If the 
operator requests that the state capital population be displayed, a CHAIN operation is 
executed on the CITY file (Figure 3-38, line 14). The capital city name contained in the 
CDA is used as the key (Figure 3-37, line 11). When the capital city name is matched in 
the CITY file, the capital city population is displayed on the UNISCOPE 100 (Figure 3-39, 
line 20). If the terminal operator does not request the capital population, the output 
message length is set to zero (Figure 3-39, line 16). In either case, termination is normal. 


Figures 3-36 through 3-39 illustrate the specifications forms required to code ACT2, the 
second action program, which accesses the CITY file for capital population. A line-by-line 
description is provided. : 
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Figure 3—37. ACT2 Input Format Specifications Form 
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Figure 3—38. ACT2 Calculation Specifications Form 
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Figure 3—39. ACT2 Output Format Specifications Form 
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IMS 90 APPLICATIONS Update A 
Explanation of Figure 3-36: 
Line Explanation 
1 ACT2 is the name of the action program (columns 75-80). The letter A in column 


74 indicates that this is an action program. 


2 The primary input file is one record - the IMS 90 IMA. 

3 The OMA is specified as an output file. 

4 The CDA is specified as a demand input file. 

5 The logical file (CITY) is specified as an ISAM chained disk file containing fixed- 


length records (46 bytes) processed randomly by alphanumeric keys 25 bytes 
long beginning in position 1 of the record. Labels are standard. 


Explanation of Figure 3-37: 


Line Explanation 
6, / Only one field of the IMA is used. The header information (1-16) is not used. 
© 8,9 The records of the CITY file contain the capital population in positions 26-32. 


10, 11. The CDA contains, in positions 1-25, the state capital which was passed to ACT2 
by ACT1. 


Explanation of Figure 3-38: 


Line Explanation 

12 The terminal operator reply is checked to see if it was YES. 

13 If the reply is YES, the CDA containing the capital city name is read. 
14 The capital population is then retrieved from the CITY file. 





y 


Y 
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Explanation of Figure 3-39: 
Line Explanation 
15, 16 If the reply is not YES, the output message length is set to zero. 


17, 20 If the reply is YES, the capital population is displayed. Line 19 sets up the DICE 
control characters. 


ACT1 and ACT2 illustrate passing capital city name in the STATE logical file from one 
action program to another as a key to retrieve capital city population requested from the 
CITY logical file. 


3.16.3. Screen Formatting Example 


The following program, EMPINQ, is an action program that processes screen formatted 
messages. When the terminal operator keys in the IMS 90 transaction code followed by an 
8-digit employee number, the program retrieves the employee's record from a disk file and 
displays the name and address on a predefined screen format. When an employee number 
is not found in the file, another screen format displays an error message. Figures 3-39A 
through 3-39D show the specification forms required to code action program EMPINQ. 


Here is an explanation of Figures 3-39A through 39D: 


Line Explanation 
1 Columns 74-80 indicate that this program is an action program named EMPINQ. 
2 Line 2 defines the IMS 90 IMA file named SCRNIN. SCRNIN ts the input primary 


file and contains fixed-length records. The record length of 27 bytes consists of 
16 bytes for the IMA header, 2 bytes for the transaction code, 1 blank byte, and 
8 bytes for the employee number. | 


3 Line 3 defines the user disk file, EMPFILE, which contains employee records as 
an input chained file (IC In columns 15 and 16), meaning that records are 
processed randomly from an indexed sequential file (| in column 32). EMPFILE 
records are fixed in length at 100 bytes and blocked 100 bytes. Column 30 
indicates an 8-byte key field (employee number) ts used to access this file 
randomly (column 28), using a record address (A in column 31). The 8-byte key 


Starts in byte 1 of the record (column 38). The file is stored on a disk device | 


(column 40-46) and has standard labels (S in column 53). 


4 Line 4 defined the IMS 90 OMA file name SCRNOUT as an output file (O in 
column 15) with fixed-length records (F in column 19). The record length of 103 
bytes consists of 16 bytes for the OMA header, 8 bytes for the employee number, 
and the remaining 79 bytes for the name and address of the employee. 
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Figure 3—39B. EMPINQ, Input Format Specifications Form 
Figure 3—39C. EMPINQ, Calculation Specifications Form 
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Figure 3—39D. EMPINQ, Output Format Specifications Form 
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Explanation 


The IMA file SCRNIN includes an 8-byte employee number entered as an input 
field from the terminal. Columns 15 and 16 indicate that no retrieval sequence is 
required for this record type in relation to other record types in the file. There are 
two record types on input. The first record type is shown by the 01 indicator. 
(columns 19-20). Indicator 01 is set on when the terminal operator enters the 
employee number. 


These lines define the disk record for the chain file EMPFILE. When the CHAIN 
operation occurs (line 13) and the employee record is found, the record- 
identifying indicator 02 (column 19-20) is turned on. 


The CHAIN operation retrieves the employee record using the employee number 
as a key. When the record is found in the disk file, indicator 02 is set on. When 
the record is not found, indicator 99 is set on. 


Line 14 defines the IMS 90 OMA file as a detail type output record (D in column 
15). If indicators O1 and O2 are on, IMS 90 sends the screen format INFOFMT 
and the name, street, city, state, and zip code of the employee (variable fields 
described on lines 15 through 20) to the terminal. The end position of employee 
number is 24 because the OMA header uses the first 16 bytes and the employee 
number is 8 bytes long. The K7 in columns 42 and 43 indicates the number of 
characters contained in the format name (INFOFMT) that is defined as a constant 
in columns 46-52. 


Line 21 defines the error screen format as a detail type record. If the employee 
number is not found in the disk file, RPG Il sets indicator 99 on and IMS 90 
sends the error screen format ERRORFMT to the terminal. K8 in columns 42 and 
43 indicates the number of characters contained in the format name 
(ERRORFMT) that is defined as a constant in columns 46-53. Line 23 defines the 
variable data field of the employee number that follows the 16-byte output 
message header. 


Both screen formats INFORFMT and ERRORFMT must be constructed separately at screen 
format generation time. This process defines the display constants, including the error 


message 


NOT FOUND IN FILE, which is itself a display constant. The RPG II action 


program then must supply the exact variable data needed by the screen formats. 


Figure 3-19A shows the results of the complete output screen format (INFOFMT) 
containing display constants (shaded fields) and the variable data supplied by this action 


program. 


Figure 3-39E shows an example of the error screen generated when an 


employee record cannot be found. Display constants are shaded. 


87654321 





Figure 3—39E. Error Screen Format 
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© 3.17. SAMPLE BAL ACTION PROGRAM 


The sample user-written action program in Figure 3-40 processes a simple inquiry 
| transaction. A sample input message and the corresponding output message are shown in 
i Figure 3-40. 


The file referenced in this transaction is the STATE file of the examples in 3.14. The 
transaction retrieves and displays the name of the capital city when the state name is 
given as input. 


—> IMS 90 associates the transaction code C with the action program ACTS in Figure 3-41. 


ACT3 uses the name of the state given in the input message as a key to obtain a record 
from the STATE file. If the record does not exist, an error message Is displayed. 


C ALASKA 


CAPITAL: JUNEAU 





=p Figure 3—40. Example of Simple Inquiry Transaction 
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1 10 16 

TITLE ‘IMS STATE CAPITAL ACTION PROGRAM’ 

PRINT NOGEN 
ACT3 START 0 ACTION PROGRAM ENTRY POINT 
* ALLOCATE REGISTERS TO COVER: 

USING *,R2 THIS ACTION PROGRAM 

USING ZA#DPIB,R3 THE PROGRAM INFORMATION BLOCK 

USING ZA#IMH,R4 THE INPUT MESSAGE AREA 

USING WORK,R5 THE WORK AREA 

USING ZA#OMH, R6 THE OUTPUT MESSAGE AREA 
* INITIALIZE 

STM 14,12,12(13) SAVE ACTION SCHEDULING REGISTERS 
‘ RD$ CONTAINS SAVE AREA ADDRESS WHEN 
: CONTROL IS RECEIVED BY 
: ACTION PROGRAM. 

LR R2,R15 ESTABLISH ADDRESSABILITY FOR ACTION 
: | PROGRAM. RF$ CONTAINS ENTRY POINT 
‘ ADDRESS WHEN CONTROL IS RECEIVED 
: BY ACTION PROGRAM. 

LM R3,R6,0(R1) ESTABLISH ADDRESSABILITY FOR 
. ACTIVATION RECORD. R1I$ CONTAINS 
: PARAMETER LIST ADDRESS WHEN CONTROL 
: 1S RECEIVED BY 
; ACTION PROGRAM. 

LA R1i0,SAVEAREA GET ADDRESS OF ACT3 SAVE AREA 

ST R18,8(,R13) SET FORWARD POINTER FROM ACTION 
' SCHEDULING SAVE AREA | 

@ ST R13,4(,R18) SET BACKWARD POINTER TO ACTION 

: SCHEDULING SAVE AREA 

LR R13,R19 MAKE ACT3 SAVE AREA THE CURRENT 
e SAVE AREA 
* GET STATE RECORD FROM FILE USING STATE NAME KEY IN INPUT MESSAGE 

1GH#CALL GET, (STATE, RECORD, SNKEY) ISSUE CALL TO IMS 99 

CLI ZAHPSC+1,8 TEST STATUS CODE RETURNED IN PROGRAM 
: INFORMATION BLOCK BY IMS 9¢ 

BNE ERROR NON-ZERO MEANS ERROR 


" BUILD OUTPUT MESSAGE 
MVC QUTTEXT(4),NEWLINE PUT DEVICE INDEPENDENT CONTROL 


: CHARACTERS INTO MESSAGE TO CLEAR 
: TO END OF LINE AND POSITION TO 
: BEGINNING OF NEXT LINE 

MVC OUTTEXT+4(L'MSGCON1),MSGCONI PUT TEXT CONSTANT INTO 
: MESSAGE 


MVC OUTTEXT+4+L‘MSGCONI(L'’SCAPITAL) ,SCAPITAL PUT CAPITAL NAME 


INTO MESSAGE 
B TERM 
" PROCESS ERROR 


Figure 3—41. Sample BAL Action Program (Part 1 of 2) 
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1 10 16 
ERROR MVC OUTTEXT(4) , NEWLINE CLEAR TO END OF LINE AND POSITION 
. TO BEGINNING OF NEXT LINE 

CLI ZA#PSC+1,1 TEST STATUS CODE 

BNE IOERROR 
: ONE MEANS INVALID KEY 

MVC OUTTEXT+4(L‘MSGCON2) ,MSGCON2 PUT’ INVALID STATE NAME’ 
. INTO MESSAGE 

B TERM 
JOERROR MVC OUTTEXT+4(L‘°MSGCON3) ,MSGCON3 PUT ‘10 ERROR' INTO 
: MESSAGE 


* TERMINATE EXECUTION OF ACTION PROGRAM BY RETURN CALL TO IMS 98. 

* THE DEFAULT TERMINATION INDICATOR IN THE PROGRAM 

* ENFORMATION BLOCK IS ‘N’ FOR NORMAL TRANSACTION TERMINATION. 

* THE DESTINATION TERMINAL ID IN THE OUTPUT MESSAGE AREA HEADER IS 
* SET TO THE DEFAULT VALUE OF THE ORIGINATING TERMINAL AND THE TEXT 
* LENGTH IS SET TO THE CONFIGURATION STANDARD LENGTH. 


TERM ZG#CALL RETURN 
EJECT 
* CONSTANTS 
STATE DC CL7‘STATE’ ISAM FILE NAME 
MSGCON1 DC C‘' CAPITAL’ 
MSGCON2 ODC C‘' INVALID STATE NAME’ 
MSGCON3 DC C' 1/0 ERROR’ 
NEWLINE ZO#POSC,8,8 ICAM PROCEDURE TO GENERATE DICE SEQUENCE FOR 
: NEW LINE CONTROL WITH CLEAR 
EJECT 
* ACTIVATION RECORD DEFINITION 
ZM#DiMH 
TCODE DS X TRANSACTION CODE 
DS X SPACE 
SNKEY DS XL4 STATE NAME KEY 
EJECT 
WORK DSECT WORK AREA 
RECORD EQU ‘ 
SNAME DS XL14 STATE NAME 
SPOP DS XL8 STATE POPULATION 
SCAPITAL DS XL25 STATE CAPITAL 
SAVEAREA DS 18A REGISTER SAVE AREA 
PLIST DS 4A PARAMETER LIST REFERENCE BY ZG#CALL MACRO 
EJECT 
ZM#DOMH OMA CONTROL HEADER 
OUTTEXT DS XL42 OUTPUT MESSAGE TEXT AREA 
REGEQU THIS PROC DEFINES MNEMONIC REGISTER NAMES 
END 


Figure 3—41. Sample BAL Action Program (Part 2 of 2) 
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4. Generating Edit Tables 


4.1. PURPOSE 


The validity of input data is a major concern in an online system. Writing validation 
procedures in an action program, however, can be a complicated and time-consuming 
process. This process can be greatly simplified by means of an offline IMS 90 utility 
program, the edit table generator (ZH#EDT), available under single-thread and multithread 
IMS 90 but not basic IMS 90. The edit table generator offers a convenient means for 
converting freeform input received from terminal operators into fixed formats required by 
action programs and checking this input for types of data, value ranges, and presence of 
required fields. 


The output of the edit table generator is written to the named record (NAMEREC) file, from 
where it is loaded at the appropriate time by applications management. Each edit table is 
associated with a particular action at configuration time by means of the EDIT parameter 
in an ACTION section. The edit table utility can be run either before or after configuration, 
but the NAMEREC file must be previously initialized. 


4.2. INPUT TO EDIT TABLE GENERATOR 
Input to the edit table generator is in the form of keyword parameters that define the edit 
table, each field of the input message to be edited, and the edit criteria for each field. 


4.2.1. Coding Rules 


The following rules apply to the coding of input to the edit table generator. Note that the 
statement conventions in Appendix A also apply. 


1. Input cards must contain sequence numbers in columns 77 through 80. Input cards 
must be presented in ascending order. The lowest permissible sequence number is 
0001. 


2. Parameters can be coded in any columns between 1 and 76. Blanks are ignored and 
are permitted anywhere in the edit table definition. 
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3. Specifications for an edit table and for each field can span more than one line. 
However, a keyword and its value must be contained on one line. 


4. A new edit table specification must start on a new line. Each field need not begin on 
a new line. 


5. The field separator character specified by the SEP keyword parameter must be used 
as the field separator throughout the edit table specification, as well as the input 
message to be edited. Double separator characters indicate the end of the edit 
definition. A new edit table can establish a different separator character. 


6. The SEP, ETAB, and KEY parameters must be coded in the prescribed order; the 
remaining keyword parameters can be specified in any order. SEP and ETAB are 
coded once for each edit table. The remaining parameters are repeated for each field 
in the input message to be edited. 


7. Numeric values are positive unless preceded by a minus sign (-). The plus sign (+) is 
not permitted in numeric values. 


4.2.2. | Input Parameters 
The character specified by the SEP parameter is used as the separator. 
Format: 


SEP=separator-character 
ETAB=tablename 
KEY=({keyword 

position 
LEN=field-length 
POS=starting-position 
CFit=fill-character] 


ary 
aa 


(MAX=maximum-value] 
(MiN=minimum-value] 











TYP=/A 
B 
¥ 
N 
p 
where: 


SEP=separator-character 
Specifies the field separator character for both the edit table definition and the 
input message to be edited. It can not be a blank, equal sign, or minus sign. This 
parameter is required, must be the first entry on the first line of the edit table 
definition, and can be specified only once per edit table. 
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ETAB=tablename 


KEY 


LEN= 


NOTES: 


Identifies the edit table and must immediately follow the SEP parameter. This 
specification associates the edit table with an action at configuration, via the 
EDIT=tablename option in the ACTION section. 


The tablename must be 2 to 7 alphanumeric characters, the first of which must 
be alphabetic. 


Identifies the input message field for which edit criteria are specified in 


subsequent parameters and must be the first parameter specified for each field. 


The edit table generator associates all subsequent specifications with this field 
until another KEY parameter is encountered. 


Input message fields can be positional or keyword. Positional fields are defined 
by a numeric specification in the KEY parameter (e.g., KEY=1). Keyword fields 
are defined by an alphanumeric specification (e.g., KEY=AMT). Positional fields 
must precede keyword fields and must be specified in order, beginning with 1. 
Once a keyword field is defined, all additional fields must be keyword; positional 
fields are no longer accepted for the current edit table. 


KEY=keyword 
Specifies a 1- to 3-character alphanumeric identification, the first character 
of which must be alphabetic, for a keyword field in the input message. 
Keyword fields must be entered at the terminal in the form keyword=data. 
Once a keyword field is identified in the edit table definition, all subsequent 
fields must be defined as keyword fields. 


KEY=position 
Specifies the sist position of the field as it appears in the input message. 
Positional fields must be defined in numeric order, starting with 1. The first 
field in an input message is always the transaction code, and this must 
always be specified as a positional field. 


field-length | 

Specifies the length of the edited field as required by the action program and is a 
required parameter. A maximum of 255 characters can be _ specified for 
alphanumeric fields and four characters (one full word) for binary fields. Ten 
characters is the maximum length for numeric fields unless both MIN and MAX 
parameters are specified for this field. !f a numeric field is identified in the action 
program as packed decimal, up to 16 characters can be specified. 


1. If the field-length is larger than the width of the screen on which data ts to be 
entered, INix 90 removes the DICE code at the end of each line of terminal input and | 
replaces it with a blank character. These additional blank characters must be provided 
for in the action program and included in the field-length specified by the LEN 
parameter. 
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2. The length specified for both binary (TYP=B) and packed (TYP=P) fields must equal 
the length for each binary or packed item in the input message. For example, if a field 
is defined as packed with a LEN=3 then a number keyed in at the terminal cannot be 
1000 or greater. This will cause an error stating your input field is too large, even 
though 1000 may be represented in a packed field in 3 bytes. 


3. If the transaction code (the first field in the input message) its less than five 
characters, the terminal operator must key in a space before entering the separator 
character for the next field. The space its included in the field-length specified by the 
LEN parameter. For example, if the transaction code is PAY, the operator must key in 
PAYA, and the LEN parameter must be specified as LEN=4. 7 


The length of the first field can be greater than five characters, but only the first five 
characters are used in the transaction code. The LEN parameter should specify the 
actual length of the field. 


POS=starting-position 
Specifies the starting position of this field as it appears in the edited message 
and is a required parameter. The first field starts at 0. The maximum permissible 
specification is 32,767. 


Fil=fill-character 

Optionally specifies the fill character to be inserted in the edited field when the 
field as input from the terminal is less than the field-length specified by the LEN 
parameter. The default fill character is O. If spaces (X‘40’) are desired as fill 
characters, this parameter can be coded as either FIL= or FIL=A; i.e., a space 
can be included or omitted before the separator character for the next field. 
Binary fields are always filled with binary zeros; therefore, this parameter is 
ignored if specified for a binary field. 


JUS=L 
Specifies left justification of this field in the edited message. Binary and packed 
fields are always right-justified; therefore, this parameter is ignored if specified 
for a binary field. 


JUS=R | 
Specifies right justification of this field in the edited message and is the default 
assumption. | 


eee, 
SSRE 


Specifies that this field is not mandatory in the edited message in order for input 
to be acceptable. 


MAN=Y 
Specifies that this field is mandatory in the edited message. 


MAX=maximum-value 
Specifies the maximum value allowed for the field in the input message. This 
parameter is applicable only to numeric fields. The highest value that can be 
specified is 23'-1. The number of characters in this value must not exceed the 
length specified by the LEN parameter. 
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© MIN=minimum-value 


Specifies the minimum value allowed for the field in the input message. This 
parameter is applicable only to numeric fields. The lowest value that can be 
specified is -(23'-1). The number of characters in this value must not exceed the 
length specified by the LEN parameter. 





Specifies the type of data to be contained in the edited field. 


TYP=A 
Specifies alphabetic data. A field defined to the editor as alphabetic is 
treated as an alphanumeric field. 


TY P=B 
Specifies binary data. 





‘Specifies alphanumeric data. 


TY P=N 
Specifies numeric data. 


TYP=P 
e Specifies packed decimal data. 


4.3. EXECUTING EDIT TABLE GENERATOR 


4.3.1. Sample Execution Run Stream 


Once input parameters describing the edit table format are specified on cards and the 
NAMEREC file has been initialized, the ZH#EDT edit table generator utility can be executed 
using the control stream illustrated in Figure 4-1. 


JOB ADDEDT, ,AGBS 

DVC 26 // LFD PRNTR 

OPTION DUMP 

DVC 58 // VOL DS9999 // LBL NAMEREC,DS9999 // LFD NAMEREC 
EXEC ZH#EDT 


source cards 


source cards 





Figure 4—1, Sample Execution of Edit Table Generator 
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Note that the LFD name of the NAMEREC file is NAMEREC, not ISAMNRF as must be 
specified for the NAMEREC file utility and the data definition processor. 





lf the input definition is acceptable, the generated edit table is written to the NAMEREC 
file and the following message is issued: 


tablename ADDED 


If the edit table has the same name as a table already existing in the NAMEREC file, the 
new edit table replaces the existing table, and the following messsage is issued: 


TABLE ADDED, DUPLICATE DELETED 
lf errors cause rejection of the edit table, the following message is issued: 


tablename REJECTED 


Another way to determine edit table errors is to look at the UPSI byte. The following UPSI 
byte values pertain to the edit table error status: 


40 Warning. ZH#EDT continues processing edit table input parameters 
but no edit table is built. 


Fatal error. Edit table processing terminates. 


4.3.2. Error Processing 









When the edit table generator encounters a file |/O error or certain types of input errors, 
it terminates and prints a message in the output listing. The resulting value in the UPSI 
byte is 80. Most types of input errors do not cause termination. Processing and validation 
continues, but an error message is printed and the edit table is rejected. Input 
specifications for the edit table generator are not printed in the output listing. This type of 
error results in an UPSI byte value of 40. 


If an I/O error occurs while reading input to the edit table generator, the following 
message is issued, and the program terminates with an UPSI byte value of 80: 


INPUT READ ERROR, SCAN TERMINATED 


If an error occurs while opening, reading, or closing the named record file, the following 
{ error message is issued and the program terminates with an UPSI byte value of 80: 


FILE ERROR, SCAN TERMINATED & 
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© Errors in the input statements are reported in the following format: 
nonn ce error-message-text 
where: 
nnnan 
Is the sequence number in columns 77 through 80 of the card containing the 


error. 


cc 
Is the column number of the beginning of the input text that is in error. This 


column number is suppressed if the error is detected during final validation of all 
parameters for a given field. 


error-message-text 
ls the description of the error as listed in Table 4-1. 
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An example of an input statement error and the resultant error message is as follows: 





Input: 





SEP=,ETAB=EDIT1 ,KEY=1,LEN=5,POS=0, JUS=X,MAN=Y 0002 
Frror message: 
0002 39 JUSTIFICATION ILLEGAL 
Table 4-1 lists alphabetically the message texts inserted into the input statement error 


message. In each case, processing continues, unless otherwise indicated in the 
explanation column. 


Table 4—1. Edit Table Diagnostic Messages (Part 1 of 2) 


Error Message Text Explanation 


B TYPE LENGTH GR THAN 4 Four characters (one full word) is maximum 
CARDS NOT !IN SEQUENCE Scan terminated, run aborted* 


DIGIT MUST BE NUMERIC The value specified for the LEN, MAX, or 
MIN parameter was not a numeric value. 


DOUBLE SEPARATOR MISSING 

























Warning only; end-of-file encountered while 
searching for separator 


DUPLICATE NAME Duplicate name for nonpositional field 


nonpositionals started 


INVALID MAN SPECIFICATION Only Y or N accepted 
INVALID NAME Name too long or contains invalid characters 


INVALID SEPARATOR 


JUSTIFICATION ILLEGAL Only R or L accepted 
KEYWORD ETAB MISSING Self-explanatory 


KEYWORD INVALID Self-explanatory 
KEYWORD SEP= MISSING Scan terminated, run aborted* 


LEN OR POS EXCEEDS MAX Maximum length is 255; maximum position is 
32,/67 


*These errors set the UPSI byte to 80; all other errors in this table result in an UPSI byte vaiue of 40. 





Scan terminated, run aborted; = and - are not 
allowed as separators* 






















4 


f 
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Table 4—-1. Edit Table Diagnostic Messages (Part 2 of 2) 


LEN OR POS MISSING Required parameters 


LEN ZERO A zero value was specified for the LEN 
parameter 
Value must be greater than zero 


MAX OR MIN ABSOLUTE VALUE TOO LARGE | 23'-1 is largest absolute value allowed 


MAX VALUE LESS THAN MIN The value specified for the MAX parameter 
is less than the value specified for the MIN 
parameter 


N TYPE LENGTH GR THAN 10 Ten characters is maximum unless MAX and 
MIN both specified 

NO DEFAULT FOR THIS FIELD Parameter value must be specified 

NO FIELDS DEFINED Empty table not allowed 


P TYPE LENGTH GR THAN 16 Sixteen characters maximum for packed 
decimal! field 


~ SiGN MUST FOLLOW KEYWORD 


TOO MANY FIELDS Scan terminated, run aborted; output buffer 
overflow* 
xxx OVERLAPS yyy Warning only; overlapping fields permitted 


*These errors set the UPS! byte to 80; all other errors in this table result in an UPSI byte value of 40. 


























4.4. ENTERING INPUT MESSAGES FROM TERMINAL 


When an input message for which an edit table has been generated is entered from the 
terminal, it is processed by an IMS 90 component called the expanded input editor. The 
following considerations apply to the entering of these input messages. 


m The transaction code must be the initial field of the message. The first field of the 
edited message at execution time may be two characters or longer; however, if the 
first field is longer than five characters, only the first five characters are used as the 
transaction code to schedule the action programs. 


= Positional fields begin with the first nonblank character and extend to the next 
separator. Positional fields must appear in the input message in the same order as 
specified in the edit table definition. If a positional field is omitted, a separator 
character must be entered to indicate its position. Positional field editing is terminated 
when all positional fields have been edited, when a keyword field is encountered, or 
when end of data has been reached. A positional field may not contain an equal sign. 


= Keywords must be followed by an equal sign with no intervening blanks. Data starts 
immediately after the equal sign and extends to the next field separator. 
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=» Numeric values are positive unless preceded by a minus sign. The plus sign (+) is an 
invalid character. 


= Error messages are displayed on the first line of the display terminal: therefore, it is 
recommended that input messages be started on the second line so that the input is 
not erased by an error message. 


= = If fields are continued from one line to another, IMS 90 removes the DICE code at the 
end of each line and replaces it with a blank character, which is sent to the action 
program as part of the data. Fields that do not exceed the width of the screen should 
always be entered on one line. If a field exceeds the screen width and must be 
continued from one line to another, the terminal operator should avoid splitting a 
word between lines, and the action program should provide for the additional blank 
characters. : 


# If the terminal input ends with a positional parameter (no keyword parameters are 
specified), the separator character must end the input message; otherwise, the input 
message could be partially deleted. A correct terminal entry is: 


INFOR,BIOLOGY,CLASS2,MARY J. BLISS, 


4.5. SAMPLE APPLICATION 


Figure 4-2 and Table 4-2 describe sample input to the edit table generator for an accounts 
receivable application where the edited input is to be delivered to the action program in 
the following format: 


65 69 


0 5 






~ SHIP 
NUMBER 






TRANS NAME ADDRESS AMOUNT 


ID 





1 
SEP=,ETAB=EDIT1,KEY=1,LEN=5, POS=8, MAN=Y, 
KEY=2,LEN=20, POS=5, FIL=, JUS=L,MAN=Y, 


KEY=3, LEN=40,P0S=25,FIL= , JUS=L, 
KEY=AMT,LEN=4, POS=65, MIN=1999, TYP=B ,MAN=Y,FIL=8, JUS=R, 
KEY=SN, LEN=6,P0S=69,FIL=, JUS=R,, 





Figure 4—2. Sample Input to Edit Table Generator 
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ETAB=EDIT1 
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Table 4—2. Description of Sample Input to Edit Table Generator 


The field separator is a comma for both the edit specification and input from the terminal. 


The edit table name is EDIT1. 


The first field described is positional. It must be the first field in the input message. This 


field is always the transaction-id. 

The edited field ts five characters long. 

in the edited message the field begins in position O. 

The field must be present for the message to be acceptable. 

The field is positional. It must be the second field in the input message. 
The edited field is 20 characters long. 

In the edited message the field begins in position 5. 


The field is to be blank fifled in the edited message. 


The field is to be left-justified in the edited message. 


The field must be present for the message to be acceptable. 


The field is positional. It must be the third field in the input message. 


| The edited field is 40 characters long. 


In the edited message the field begins in position 25. 

The field is to blank filled in the edited message. 

The field ts to be left-justified in the edited message. 

The field is a keyword field. AMT=n must be specified in the input message. 

The edited field is three characters long. 

In the edited message the field begins in position 65. 

The minimum level allowed for the message to be acceptable is $10.00 (entered as 1000). 
In the edited message the field is to be converted to binary. 

The field must be present for the message to be acceptable. 


The field is to be zero filled in the edit message. (This parameter could have been 
omitted.) 


The field is to be right-justified in the edited message. (This parameter could have been 
omitted.) 


The field is a keyword field. 

The edited field is six characters long. 

In the edited message, the field begins in position 68. 
The field is to be blank filled in the edited message. 


The field is to be right-justified in the edited message. (This parameter could have been 
omitted.) 


End of edit definition. 
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The following examples represent freeform input from the terminal and the resulting 
messages sent to the action program in accordance with the specifications in the edit 
table generated for this application or, in case of error, the output message displayed at 
the terminal. Note that in these examples, the 4-character binary field specified for the 
AMT entry is represented by an underlined, 4-hexadecimal-digit field. Spaces between 
each delimiter and the first character of the next field are ignored. 

Terminal Input: 


PAYMT, JOHN D. SMITH,1112 BREEZE DR. PHILA. PA. 19160, 
AMT=2500,SN=123456 


Edited Message: 
PAYMTJOHNAD.ASMITHAAAAAAA1112ABREEZEADR.APHILA.APA.A19160 


AAAAAAAAOYC4 123456 


Terminal Input: 
PAYMT,JOHN D. SMITH,,SN=123456,AMT=2500 
Edited Message: 


PAYMTJOHNAD.ASMITH AA AAAAAAADAAAAAAAAAADAAAAADAAAAAAAA 
AAAAAAAAAAAAAODYC41 23456 


Explanation: 
The address field was not specified as mandatory in the edit table input and is 
omitted here; an additional comma is coded in its position. The AMT and SN fields are 
keyword fields and need not be entered in the order defined in the edit table input. 


Terminal Input: 


PAYMT JOHN D. SMITH,1112 BREEZE DR. PHILA. PA. 19160, 
AMT=2500,SN=123456 


Output Message: 
ILLEGAL INPUT 
Explanation: 


The transaction code field is longer than the LEN specification. 
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a a I a ere re re 
Terminal Input: 


PAYMT,JOHN D. SMITH,1112 BREEZE DR. PHILA. PA. 19160, 
AMT=700,SN=123456 


Output Message: 
AMT IS BELOW MIN 
Explanation: 


Edit table specifies AMT must be at least 1000 


Terminal Input: 

PAYMT, JOHN D. SMITH,1112 BREEZE DR. PHILA. PA. 19160,SN=123456 
Output Message: 

AMT MISSING 
Explanation: 


AMT was specified as mandatory. 
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5. Terminal Operation 


5.1. TERMINAL I/O MESSAGE PROCESSING 


IMS 90 terminal operation is concerned with the transmitting and receiving of messages. 
For every message transmitted by the terminal operator, there is always at least one 
output response. Input messages are of two types - transaction messages and terminal 
commands. | 


Transaction messages are related to action programs, both IMS 90 and user-supplied. 
Because several actions can be linked together to form a transaction, each transaction can 
include a series of input and output messages. Each transaction is initiated by a 1- to 5- 
character transaction code. 3 


When you use the uniform inquiry update element (UNIQUE), file processing transactions 
are performed by means of UNIQUE commands. (See Section 6.) The OPEN command is 
the transaction code that initiates UNIQUE processing. 


File processing functions also can be performed by user-written action programs via user- 
defined transaction codes and embedded messages. IMS 90 also provides transaction 
codes for communicating between terminals (SVWTCH), displaying the last valid output 
message (DLMSG) for recovery purposes, downline loading user programs to a UTS 400 
terminal (DLOAD), and displaying statistical information (ZSTAT). 


Administrative and control functions are handled by IMS 90 terminal commands. Master 
terminal commands allow overall monitoring of the system and control of the 
communications network, while standard terminal commands perform administrative and 
operational functions for the individual terminal. All terminal commands start with the 
letters ZZ. 


5.1.1. Initiating Online Processing 


After the IMS 90 start-up procedure has been performed, as detailed in the IMS 90 system 
support functions user guide/programmer reference, UP-8364 (current version), the 
message IMS READY appears on each terminal that is in a ready state, unless you have 
chosen, by configuration, the option of not receiving the IMS READY message. The 
terminal operator can then begin transmitting messages. This message appears only once, 
at start-up time. Terminals coming online at a later time do not receive IMS READY unless 
they are marked down at the time IMS 90 is initiated. 
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5.1.2. Transmitting Messages from Display and Hard Copy Devices © 


When commands and other messages are issued from a display device, the terminal 
operator must enter the message and press the TRANSMIT key. If input is from a hard 
copy device (e.g., SPERRY UNIVAC DCT 500 Data Communications Terminal or a 
teletypewriter), an end-of-text (ETX) character must follow the last character of the 
message. In both cases, commands and transaction codes must be entered in uppercase if 
the translate option has not been configured. 


When a hard copy device is used, characters or messages erroneously entered can be 
deleted through the use of control characters. The control characters are: 


Control 
Function Character 
Delete a character H 
Delete a message xX 


More than one character can be deleted by entering the H consecutively as ney times as 
there are characters to be deleted. 


5.1.2.1. Transmitting DICE Sequences from Hard Copy Devices 


On hard copy devices, device-independent control expression (DICE) sequences are 
transmitted to action programs by means of the carriage return key and the line feed key. 


Before keying in the UNIQUE command OK or CANCEL to execute or cancel an ADD, 
CHANGE, or DELETE transaction on a hard copy device, the operator must press the 
carriage return key and the line feed key. This is necessary because UNIQUE expects to 
receive the DICE sequence before an OK or CANCEL command. If the operator does not 
press these keys before transmitting an OK or CANCEL command, IMS 90 cancels the | 
transaction and returns an INPUT ALTERED message to the terminal. (If this occurs, the | 
operator reenters the UNIQUE update operation.) 


On the other hand, whether the operator should or should not press these keys before 
keying input for a user-written action program depends upon whether editing of input 
messages has been specified for the action at configuration time and what the action 
program expects to receive as input. If no editing has been specified and the keys are 
pressed, IMS 90 passes the 4-byte DICE sequence to the action program that receives 
control to be processed. If input editing has been specified, the DICE sequence is stripped 
entirely (except for the (CR) DICE sequence, which is replaced by a blank). The action 
program must be able to accept such characters in the input, and the terminal operator 
must be appropriately instructed. 
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5.1.2.2. Handling Multiline Terminal Messages 


When keying in an input message at the terminal, the carriage return (CR) DICE sequence 
(10040000,,) is replaced by one blank character (40,.), unless the carriage return DICE 
sequence precedes valid input text or unless the EDIT=NONE parameter is specified in the 
ACTION section of the configuration. If the carriage return sequence precedes valid input 
text, it is deleted completely. If NONE is specified, the input message is transmitted to the 
action program unedited. 


For example, if the word “END” is divided between two lines at the terminal in this 
manner: 


beet Ha eee sath 9 as gees Sh ee te ek EN (CR) 


the resulting message in the input message area (IMA) of the action program would be: 


This example emphasizes that the best approach to multiline message composition is to 
use the carriage return between words to avoid embedded spaces in the resulting 
message transmitted to the IMA. Note that UNIQUE rejects fields that are divided across 


two lines. Consequently, you should avoid splitting fields in messages that use more than 
one line. 


5.1.3. Initiating a Transaction 


The first input message of a transaction must contain a 1- to 5-character transaction code 
beginning with the first character of the message. If the transaction code is less than five 
characters in length, it must be followed by a blank. If the input message begins with a ZZ, 
it is interpreted as a terminal command to be processed by IMS 90. 


Transaction codes OPEN, SWTCH, DLMSG, DLOAD, and ZSTAT initiate IMS 90 action 
programs and are reserved. Any other transaction code must be defined to the system at 
configuration time in a TRANSACT section or it will be rejected as invalid input. In a dialog 
transaction, all input messages after the first are not examined for a transaction code and, 
in fact, may contain any characters in the first one to five positions except for ZZ. 


Transactions can be initiated only from terminals and not from the system console. A 
transaction can be initiated by a function key if the function key has been defined at 
configuration in a TRANSACT section. A transaction can be initiated only when the 
previous transaction or terminal command has been resolved in its entirety. If a 
transaction code is entered prior to the resolution of the previous input, it is treated as 
unrecognizable input and is ignored. 


When an output message requires an input response, that response must be transmitted 
prior to the initiation of another transaction. 
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5.1.4. Solicited and Unsolicited Output 


The initial output received at a terminal in response to an input from the terminal is called 
solicited output. Solicited output is unconditionally transmitted when it becomes available. 


Unsolicited output is any output other than the initial response to a message from the 
same terminal. It is available only if specified at configuration. There are two types of 
unsolicited output: 


» Additional output to the initiating terminal after the original output (i.e., segmented 
output). When the volume of output is greater than the screen size of the initiating 
terminal, it must be transmitted in segments. 


= Output received at a terminal as a result of an input from another terminal (i.e., 
switched output). 


To avoid the possibility of unsolicited output conflicting with the terminal operator's efforts 
(e.g., developing a screen of data for input), IMS 90 warns the terminal operator of 
pending unsolicited output via an unsolicited output indicator as listed in Table 5-1. 


Table 5—1. Unsolicited Output Discipline 


Display Devices Hard Copy Devices } 


Unsolicited Message /CMW* 
output indicator waiting light 


Acceptance Press message Transmit bell 
response waiting light key. Press CTRL G. 
Press CTRL C. 





















*The unsolicited output indicator to a hard copy device is a 4-character message 
defined by the MSGWAIT keyword parameter of the TERM macro in the CCA 
definition. The default is /CMW. Refer to the ICAM network definition and 
operations user guide, UP-8947 (current version). 


When output ts segmented, the unsolicited output indicator is displayed prior to each 
segment. The operator must accept all segmented output. 


lf the unsolicited output indicator is displayed to notify the terminal operator of the 
availability of a message sent from another terminal, the operator can ignore the signal 
and transmit an input message, or he can accept the unsolicited switched message by 
pressing the message waiting key on display devices or by pressing simultaneously the 
CTRL and G followed by the CTRL and C keys (ETX) on hard copy devices. 


If more unsolicited messages are waiting, the unsolicited output indicator is sent again 
and the operator can again ignore the signal or accept the message. 


The switched output indicator will appear at a terminal only if that terminal is not in 
interactive mode, unless UNSOL=ACTION is specified to the configurator in the TERMINAL 
section. 
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When handling segmented or switched output, it is advisable to indicate output disk 
queueing in the ICAM network definition. 


5.1.5. Function Keys 


Function keys F1 through F4 on the UNISCOPE display terminal F1 through F22 on the 
UTS 400 terminal and F1 through F33 on the IBM 3270 terminal provide a fast, efficient 
method of accessing user-written action programs. A function key can be used in either of 
two ways - as a transaction code or as a response to an output message. A function key 
used as a transaction code must be defined to the configurator in the TRANSACT section. 
A function key used as an input response is defined in the action program. 


The same function key can be used for both purposes. If the terminal is in interactive 
mode, the function key calls in the successor action program identified in the previous 
action. If the terminal is not in interactive mode, the function key is interpreted as a 
transaction code. 


Function keys can be entered from a hard copy terminal by keying in F#nn, where nn is 01 
through 33. 


5.1.6. Automatic Status Messages 


© One of the following automatic status messages is output by IMS 90 (multithread only) to 
notify a terminal operator of the status of the last input message. The appropriate status 
message is sent to the terminal periodically until the end of the current action: 


Automatic Status Message Meaning 


INPUT IN QUEUE IMS 90 has received the input message but has not 
yet delivered it to the action program. 


INPUT IN PROCESS The action program has received the input message 
and is processing it. 


ROLLBACK IN PROCESS The action program has terminated abnormally, and 
the updated user data files are being restored to the 
last rollback point. 


At any point after the first status message, the terminal operator can cancel the current 
transaction via the ZZCNC command (5.2.1.6). Any input other than the ZZCNC command 
transmitted prior to the response output message is ignored. 
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5.2. TERMINAL COMMANDS 


Terminal commands are used for various administrative, operational, and control 
functions. Master terminal commands are used to control the overall system and the 
communications network, while standard terminal commands are used by the individual 
terminal operator to control the flow of messages at his terminal. All terminal commands 
begin with the characters ZZ. Table 5-2 summarizes the master and standard terminal 
commands supported by basic, single-thread, and multithread IMS 90. They are described 
in 5.2.1 and 5.2.2. 


Table 5—2. IMS 90 Terminal Commands 


Master/ 
Standard 
Master Designates an aiternate terminal 


Master 


Command 


Single-Thread Multithread 





ZZALT 


ZZBTH Initiates and controls batch processing of 


transactions in online mode from the master terminal 
(Refer to 7.6.1) 


Master Closes files from master terminal 
Standard Cancels the current transaction 
Master Closes a terminal down from master terminal 


Standard 





ZZCLS 


Y 


ZZCNC 


ZZHLD Suspends output to a terminal temporarily not 


ready to receive it 


ZZHLT Causes immediate shutdown of activity from 


master terminal or system console* 


Standard Changes master terminal 


Standard 


Master 





ZZMCH 


ZZNRM Reverts to normal mode after terminal has been 


in test mode (ZZTMD) 


Master Opens files from the master terminal 
Permits IMS 90 to load recompiled action programs 


Reports that terminal is now ready for output 





—_ ZZOPN 


ZZPCH 


ZZRDY Standard 


suspended by ZZHLD command 


Standard Causes last initial response message to be retransmitted 


Master 





ZZRSD 


ZZSHD 


Causes orderiy cessation of IMS 90 from master 


terminal or system console* 








Z2ZTCT Obtains status of terminal control table from master 


terminal 


Standard Places a terminal in test mode 


Master Tests whether a terminal on network is able to 
receive output 
Master Brings terminal online from master terminal +s 


*If OPCOM=YES has been specified to the configurator in the OPTIONS section, the multithread IMS 90 user has the option of sending 
this master terminal command from the system console at any time. This command should be keyed in as an unsolicited message 
to the IMS 90 job. 


Master 


ZZTMD 


ZZTST 


ZZUP 
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5.2.1. Standard Terminal Commands 


Standard terminal commands can be submitted from any terminal and are used at the. 
operator's discretion to control transmittal, testing, and cancellation of messages. They are 
discussed in 5.2.1.1 through 5.2.1.6. 


5.2.1.1. ZZRSD (Resend) 


The ZZRSD command directs IMS 90 to retransmit the last transaction-oriented output 
message displayed at the calling terminal. Terminal command responses cannot be resent 
except for ZZCNC, ZZCLS, ZZOPN, and (multihead) ZZTST. Once a new input message (other 
than the ZZRSD terminal command) is initiated, the preceding output message cannot be 
retransmitted, and the response NO MSG IN QUEUE is displayed. The ZZRSD command can be 
Initiated only when there is no unresolved input message; it is allowed for only one 
retransmission of an output message. It is not available if RESEND=NO is specified to the 
configurator in the OPTIONS section. 


5.2.1.2. ZZHLD (Hold) 


The ZZHLD command directs IMS 90 to suspend all output to the initiating terminal until a 
ZZRDY command is submitted. This command can be initiated only when there is no unresolved 
input. You may not use the ZZHLD command at a local workstation because it locks the 
workstation. A typical situation for use of the ZZHLD command is if the ribbon broke or the paper 
jammed on the hard copy device. 


On the UNISCOPE 100 and 200 display terminals, the operator must press the WAIT switch to 
allow subsequent input after transmitting the ZZHLD terminal command; this means that the 
WAIT switch must be pressed before transmitting the ZZRDY command to resume receiving 
output. On UTS 400 terminal; the operator must press the KBOARD UNLOCK switch before 
transmitting the ZZRDY command to resume receiving output. 


5.2.1.3. ZZRDY (Ready) 


The ZZRDY command directs IMS 90 to release the hold state on the initiating terminal 
and to transmit output as it becomes available. This command is valid only if initiated 
while the terminal is in the hold state; if submitted at any other time, it has no effect. 


5.2.1.4. ZZTMD (Test Mode) 


The ZZTMD terminal command directs IMS 90 to place the initiating terminal in test mode. 
When a terminal is in the test mode, there is no physical alteration of data files; any 
command to alter a data file (ADD, DELETE, CHANGE) is simulated. The uses of the 
ZZTMD command are: 


1. to allow new or revised action programs to be tested and debugged without risking 
the compromise of online files; and 


2. to permit training of terminal operators without causing actual update transactions to 
be made against user files. 
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When the session of testing or training is completed, the command ZZNRM is issued to 
revert to normal operating mode. Neither the ZZTMD nor the ZZNRM command can be 
issued while the initiating terminal is operating in interactive mode; that is, in the midst of 
a transaction. 


5.2.1.5. ZZNRM (Normal Mode) 


The ZZNRM command directs IMS 90 to return the initiating terminal to normal mode, 
thus enabling alteration of data files as authorized. This command is valid only if initiated 
while the terminal is in the test mode. !f submitted at any other time, it has no effect. 


5.2.1.6. ZZCNC (Cancel) 


The ZZCNC terminal command directs IMS 90 to cancel the transaction currently active. It 
does not cancel a terminal command. This command is used most often to break deadlock 
situations under multithread IMS 90 operations. It also clears all output queued to this 
terminal. It is not a command that the master terminal issues on behalf of another 
terminal, but must be initiated by the terminal experiencing the deadlock. 


Once an input has been sent, the ZZCNC command cannot be transmitted until at least 
one output message has been sent to the terminal. The output message can be a response 
message or an automatic status message. 

5.2.1.7. ZZMCH (Master Terminal Change) 

lf the master terminal is down, a new master terminal can be designated by issuing the 
ZZMCH terminal command. The ZZMCH command can be entered from any terminal. If the 
old master terminal becomes operable again during the IMS 90 session, it can be 
reactivated as a network terminal but not as the master terminal (unless the ZZMCH 


command is used again). The format of the ZZMCH command is: 


ZZMCH terminal-id 


where: 


terminal-id 
Is the configured symbolic identification of the new master terminal. 


lf the command is processed successfully, the following response is transmitted to the 
terminal that initiated the command: : 


NEW MASTER TERMINAL IS terminal-id 
lf the master terminal is not down, the response is: 


INVALID MASTER TERMINAL COMMAND 
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If the named terminal is not identified in the network definition, the following response is 
sent: 


TERMINAL terminal-id CANNOT BE FOUND 
NOTE: 
The ZZMCH command can be entered only from a configured terminal (not the system 
console). 
5.2.2. Master Terminal Commands 
Master terminal commands enable privileged control and monitoring of the IMS 90 
system. Master terminal commands must be submitted from the master terminal with two 
exceptions: ZZHLT and ZZSHD. | 
The ZZHLT and ZZSHD commands can be entered from the system console or master 


workstation (if present) in a multithread system if OPCOM=YES is configured. Master — 
terminal commands submitted from a regular terminal are rejected as invalid. 





An IMS job may have a master workstation associated with it either by means of job 
control or initiation of that job from a workstation. In either case, enter unsolicited keyins 
from the system console or the job’s master workstation. This applies to multithread — 
systems when OPCOM=YES is configured and to single-thread systems when the console 
is configured as the master terminal. Responses are always sent to the job’s master 
workstation, if present, and are only sent to the console if the job has no master 
workstation or if it has been logged off. 





The master terminal commands are described in 5.2.2.1 through 5.2.2.12. 





5.2.2.1. ZZUP (Terminal Up) 
The terminal-up command directs IMS 90 to enable a terminal that has previously been 
disabled. The typical situation for the use of this command is when a terminal, that has 


been inoperable and placed in the disabled state by the terminal-down command, becomes 
operable. 


Format: 
ZZUP terminal-id 
where: 


terminal-id 
ls the configured symbolic identification of the specified terminal. 
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5.2.2.2. ZZDWN (Terminal Down) 


The terminal-down command directs IMS 90 to disable a specified terminal. A typical 
situation for the use of this command is to logically disable a terminal that is 
malfunctioning. A terminal that is physically down is marked logically down by means of 
the ZZDWN command. Othewise, a degradation in polling can result, causing longer 
response times for active terminals. 


Format: 


ZZDWN terminal-id 


where 
terminal-id 
Is the configured symbolic identification of the specified terminal. . 
NOTE: 


It is possible to inadvertently disable the master terminal by specifying the terminal-id of 
the master terminal itself. To remedy this, control of the network can be transferred to a 
regular terminal by means of the ZZMCH command (5.2.2.8). In a multithread system, an 
orderly shutdown (ZZSHD, see 5.2.1.7) can be directed from the system console if this 
option is configured. 


5.2.2.3. ZZTST (Test Terminal) 


The test terminal command directs IMS 90 to transmit a message to a specified terminal. 
Upon receipt of the response, the master terminal is advised whether or not the test was 
successful. If the terminal being tested was disabied earlier using the ZZDWN command, 
the response message to the master terminal will indicate that the test was unsuccessful. 
The ZZTST master terminal command is used to determine whether a production terminal 
is able to receive solicited or unsolicited output. To use this command, you must specify 
the UNSOL=YES in the OPTIONS section input to the configurator. The ZZTST command is 
not available in basic IMS 90. | 


Format: 
ZZTST terminal-id 
where: 


terminal-id 
Is the configured symbolic identification of the specified terminal. 
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@ 5.2.2.4. ZZTCT (Terminal Control Table Status) 
The terminal control table status command directs IMS 90 to output to the master terminal 
the current status of the specified terminal. This output includes status of the terminal (up 
or down), outstanding activity, and volume and type of traffic since startup. 


Format: 


ZZTCT terminal-id 


where: 


terminal-id 
Is the configured symbolic identification of the specified terminal. 


In response to the ZZTCT terminal command, the following message is sent to the master 





terminal: 
STATUS OF terminat-id{UP ‘nann MSG: nnnn TRAN: nnnon TRM CMD: ALT=name 
DWN 
HLD 
TEST 
where: 
nnAan 
is the number of messages, transactions, or terminal commands. 
name 


Is the name of the alternate terminal, if specified. 


5.2.2.5. ZZALT (Alternate Terminal Designation) 


The ZZALT master terminal command directs IMS 90 to assign an alternate terminal for a 
designated terminal. Once the alternate terminal is assigned, switched output messages 
destined for the original terminal are rerouted to the alternate terminal whenever the 
original terminal is physically or logically down. Solicited and nonswitched messages are 
not affected. When the original terminal becomes operational again, message alternation 
is discontinued. The ZZALT command also can be used, without the alternate terminal-id, 
to restore the original terminal. Restrictions on the use of this command are: 





=» UNSOL=YES must have been specified in the OPTIONS section of configurator input. 


= lf the alternate terminal is physically or logically down, the switched messages are 
written on the original terminal's queue. 
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= Only one level of alternation is permitted; i.e., if B is designated as an alternate 
terminal to A, and C is designated as an alternate terminal to B, switched messages 
for A are sent to B, not C. However, the ZZALT command can be entered again to 
designate C as an alternate terminal to A, overriding the first ZZALT command. The 
ZZICT master terminal command can be used to determine what alternate terminal is 
in effect. 


= Test messages generated by the ZZTST command in single thread are not directed to 
the alternate terminal. 


The format of the ZZALT command for naming an alternate terminal is: 


ZZALT terminal-id,alt-terminal-id 


where: 


terminal-id 
Is the configured symbolic identification of the original terminal. 


alt-terminal-id 
Is the configured symbolic identification of the alternate terminal to which traffic 
is to be routed. 
lf successful, the response is: 
terminal-id IS ALTERNATED TO alt-terminal-id 


The format of the ZZALT command for restoring an alternated terminal is: 


ZZALT terminal-id 


where: 


terminal-id 
Is the configured symbolic identification of the restored terminal. 


If successful, the response is: 
terminal-id IS RESTORED 

If unsolicited output has not been configured, the following response is transmitted: 
INVALID MASTER TERMINAL COMMAND 

lf an identified terminal is not in the network, the response is: 


terminal-id CANNOT BE FOUND 
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5.2.2.6. ZZCLS (Close File) 





The close file command directs IMS 90 to close the file specified. Terminal operators are 
informed of this action only on submission of input that results in an attempt to access the 
closed file. The ZZCLS command cannot be directed to a defined file. Also, no comments 





or characters may follow the file name. cd 
Format: 
ZZCLS filename 
where: 
filename 
Is the configuration-specified file name for the file that is to be closed. 
When the ZZCLS master terminal command is issued and no currently open transactions 
have updated the file, IMS 90 issues a CLOSE macroinstruction to data management and 
sends the following message to the master terminal operator: 
filename CLOSED 
When currently open transactions are updating the file indicated in the ZZCLS command, 
IMS 90 sends the following message to the master terminal: 
filename - - IN USE BY terminal-name Y 
where: 
filename 
Identifies the file being used. A 
terminal-name 
Identifies the terminal currently accessing the file specified in the ZZCLS 
command. 
Once the terminal that was accessing the file ends the transaction, the master terminal 
operator must reissue the ZZCLS command to close the file. 
Any new user of this file after the » ZZCLS command is accepted receives file close status; 
i.e., the value 3 in the STATUS-CODE field of the PIB and the value 6 in the DETAILED- 
STATUS-CODE. Current users of the file, if any, are allowed to access the file. 
On the other hand, if the terminal operator keys in a wrong filename in the Z2CLs 
command, IMS 90 issues the following message to the master terminal: 
filename NOT CONFIGURED ' 
S$ When an attempt is made to close a common storage file, IMS 90 issues the following 


message to the master terminal: 


filename INVALID FUNCTION FOR CDA FILE 


ees 
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lf an error occurs during the closing of the specified file, IMS 90 issues the following 
message to the master terminal: 


filename CLOSE ERROR DMnn 


In addition, the data management error code is displayed and further access to the file is 


inhibited. 
NOTES: 
> 
1. When ZZCLS is issued to a sequential output file, the EXTEND parameter in the LFD 
job control statement for this file must be included to resume with the next ascending 
record number after ZZOPN. 
2. The ZZCLS command cannot be issued to a common storage area file. 
5.2.2.7. ZZOPN (Open File) 
The open file command directs IMS 90 to open a specified file previously closed via the 
ZZCLS master terminal. No comments or characters may follow the file name. 
Format: 
ZZOPN filename 
where: 
filename 
Is the configuration-specified file name for the file. 
If the operator keys in an invalid filename on the ZZOPN master terminal command, IMS 
90 issues the following message to the master terminal: 
filename NOT CONFIGURED 
When a file cannot be opened because of a conflict of access rights, IMS 90 issues the 
following message at the master terminal: 
— filename CANNOT OPEN WITH ACCESS SPECIFIED 


lf an error occurs during the opening of the specified file, IMS 90 issues the following 
message to the master terminal: 


filename OPEN ERROR DMnn 
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where: 
nn 
Specifies the data management error code. Refer to the OS/3 system messages 
programmer/operator reference, UP-8076 (current version). 
NOTES: 


1. When ZZOPN ts issued to a sequential output file. the EXTEND parameter in the LFD 
job control statement for this file must be included to resume with the next ascending 
record number after ZZOPN. 


2. The ZZOPN command cannot be issued to a common storage area file. 


5.2.2.8. ZZBTH (Batch) 


The ZZBTH master terminal command initiates and controls batch transaction processing 
in the online mode. See Section 7 for the format of this command and details of its use. 


5.2.2.9. ZZSHD (Shutdown) 


The shutdown command causes IMS 90 to terminate gracefully. The initiation of new 

© transactions is inhibited, but transactions previously initiated can continue processing. Any 
new transactions are not accepted, and a shutdown indicator is sent to terminals 
attempting to start new transactions. All terminal commands are accepted. Once there are 
no longer any outstanding transactions or a shutdown time-out has expired, whichever 
comes first, IMS 90 terminates. Any transactions not completed at that point are rolled 
back. Shutdown time-out is 180 seconds for single-thread and five times the action time- 
out value for multithread (the value given in the ACTION parameter of the configurator 
TIMEOUTS section). 


The following message is sent to terminals attempting to enter transactions after the 
ZZSHD terminal command has been transmitted: 


SHUTDOWN IN PROCESS 


5.2.2.10. ZZHLT (Halt) 


The halt command terminates IMS 90 immediately and is used only for emergencies. No 
notification is delivered to terminal operators, and transactions in process are not rolled 
back. File recovery is usually required after this type of termination, using either the offline 
recovery utility or the warm restart option at the next IMS 90 execution. 
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5.2.2.11. Z2ZPCH (Program Change) 


The program change master terminal command is used for debugging action programs. It 
allows the programmer to execute an action program online, recompile the action 
program, and then execute the new version. 


When the ZZPCH command is issued, IMS 90 locates the disk address of the new version 
of the designated program and substitutes it for the disk address of the previous version of 
the program. Then, when the action program is requested, IMS 90 loads the new version. 
You also can issue the ZZPCH command to allow IMS 90 to find an action program not in 
the load library at start-up time. In either case, the program must be identified in the 
PROGRAM section at configuration and must not be configured as resident. 


Format: 


ZZPCH program-name 


where: 


program-name | 
Specifies the name of the action program changed or updated. 


Before issuing the ZZPCH terminal command, the programmer must replace the old 
version of the action program with the new version in the IMS 90 load library. Then after 
issuing the ZZPCH command, you can execute the new action program. 


The ZZPCH terminal command should not be used for resident subprograms. If you issue a 
ZZPCH command for a resident subprogram, the first call to the resident subprogram from 
an action program canceis the transaction and IMS 90 issues the following error message: 


program-name IS A SUBPROGRAM - CANNOT BE RELOADED 


In multithread IMS 90, if the named action program is being used by another terminal, the 
following message is issued: 


PROGRAM program-name IN USE 


The operator should wait until the action program is not in use and reissue the ZZPCH 
command. The new action program can be loaded only when the current action program is 
not in use. 


The size of the new action program can not exceed the size specified in the MAXSIZE 
parameter of the configurator ACTION section. If the new size does exceed the MAXSIZE 
value, IMS 90 cancels the transaction and issues the following error message: 


PROGRAM SIZE EXCEEDS SPECIFIED MAXSIZE 


The ZZPCH master terminal command can not be issued for basic IMS 90. If you issue a 
ZZPCH master terminal command under basic IMS 90, IMS 90 issues the following 
message: 


ZZPCH NOT CONFIGURED 
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lf the action program to be changed is not configured; i.e., was never specified in the 
PROGRAM section of the configurator, IMS 90 issues the following message: 


PROGRAM program-name NOT CONFIGURED 


lf, in the ZZPCH command, you fail to enter the name of the action program to be changed, 
IMS 90 issues the following message: 


PROGRAM NAME MISSING FOR ZZPCH COMMAND 


The terminal operator must reenter the ZZPCH terminal command to supply the action 
program name. 


lf the operation of loading the new action program is unsuccessful, IMS 90 issues the 
following message: 


PROGRAM program-name LOAD ERROR 
If the ZZPCH command is successful, IMS 90 issues the following message: 
PROGRAM program-name MARKED RELOADABLE VERSION yymmdd hhmmss 
where: 


program-name 
Specifies the name of the action program containing the changes. 


yymmdd 
Specifies (in the format year, month, and day) the date of the new action 
program version being executed. 


hhmmss 
Specifies the clock.time (by hour, minutes, and seconds) of the new action 
program version being executed. 


5.3. IMS 90 TRANSACTION CODES 


The transaction codes SWTCH, DLMSG, DLOAD, and ZSTAT can be entered by the 
terminal operator to initiate special-purpose transactions performed by IMS 90 action 
programs. The SWITCH transaction code initiates terminal-to-terminal communication. 
DLMSG retrieves the last valid output message from a terminal. The DLOAD transaction 
code initiates the downline loading of UTS 400 programs from the host system to a UTS 
400 terminal system. 
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5.3.1. SWTCH (Terminal-to-Terminal Communication) & 


IMS 90 allows communication between terminals; however, excessive use of this feature 
degrades performance because the system is not designed to be used as a message 
switcher. Terminal-to-terminal communication is initiated via the SWTCH transaction code 
in the following format: 


SWI CHA(MAST -AAmessage-text 
terminal-id n,... 
ALL 
where: 
MAST 


Transmits the message-text to the master terminal regardless of the configured 
symbolic identification of the master. | 


terminal-id-n | 
Is the configured symbolic identification of the destination terminal. 


ALL 
Transmits the message to every terminal in the IMS 90 network. This parameter 
is used only when SWITCH is issued from the master terminal: it cannot be used 
in a single-thread system if the console is the master terminal. -_ 


The SWITCH transaction code must be followed by at least one blank. A comma must 
separate each terminal identification, which can have no intervening blanks. The 
semicolon denotes the end of the list of destination terminals and the beginning of the 
message text. The message text is sent exactly as it is keyed in, starting with the first 
position after the semicolon. 


Each valid destination terminal receives the message (unsolicited output) in the following 
format: 


FROM source-terminal-id-n. message text 
where: 
source-terminal-id-na 


Is the configured symbolic identification of the source terminal. 


The source terminal receives a status message indicating whether the message has been 
successfully queued to all destination terminals. If success is not complete, errors or 
exceptions are noted. Each destination terminal specified must be valid; that is, configured 
as part of the IMS 90 network. The source terminal is also informed if any destination 


terminals are down. The message is queued even if the destination terminal is physically 
or logically down. 


lf the destination terminal is down and alternated (via the ZZALT command), the message _ 
is sent automatically to the alternate terminal. The source terminal is not informed that 

the destination terminal is down. If the alternate terminal is also down, the source 

terminal is informed that the destination terminal is down. 














UP-8614 Rev. 1 SPERRY UNIVAC O0S/3 
IMS 90 APPLICATIONS 


Three different status messages may be issued: 
MSG SENT 
MSG NOT SENT INVALID DEST.terminal-id-n.... 
MSG QUEVUED. TERMINAL DOWN.terminal-id-n 
Example 1: 
Input at source terminal (TRM2): 
SWTCH TRM1,TRM4; THIS IS THE TEXT. 
Output at source terminal: 
MSG SENT. 
Output at destination terminal: 


FROM TRM2. THIS IS THE TEXT. 
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Example 2: 
Input at source terminal (TRM1, the master terminal): 
SWTCH ALL; THIS IS THE MESSAGE. 
Output at source terminal (TRM1): 
MSG SENT. 
Output at all configured terminals except the source (master) terminal: 


FROM TRM1. THIS IS THE MESSAGE. 


Example 3: 
Input at source terminal (TRM4): 
SWTCH TRM1, TRM2, TRM3, TRM5, TRM7; THIS IS THE MESSAGE. 
Output at source terminal: 
MSG NOT SENT. INVALID DEST.TRM3 
MSG QUEUED. TERMINAL DOWN.TRM2 
Output at destination terminals (TRM1, TRM5, TRM/7): 
FROM TRMA4. THIS IS THE MESSAGE. 
NOTE: 


TRM2 can receive the switched message when the terminal comes up. 


Example 4: 
TRM2 is down and alternated to TRM3. TRM3 is not down. 
Input at source terminal (TRM1): 
SWTCH TRM2; THIS iS THE MESSAGE. 
Output at source terminal (TRM1): 
MSG SENT. 
Output at terminal (TRM3): 


FROM TRM1. THIS IS THE MESSAGE. 
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Example 5: 
TRM2 is down and alternated to TRM3. TRM3 is also down. 
Output at source terminal: 
MSG QUEUVED TERMINAL DOWN TRM2 
NOTE: 


The message is on the queue of the terminal TRMS. 


Use of the SWTCH transaction code requires specification of the UNSOL=YES parameter inthe 
OPTIONS section of the configurator. Messages switched to or from the master terminal can 
only be done if the master terminal is configured as a terminal and not as the console. If the 
unsolicited output indicator is displayed (this is the message-waiting indicator ona UNISCOPE 
100 display terminal) to notify the operator of the availability of a message switched from 
another terminal, the terminal operator can ignore this signal and initiate input or accept the 
switched message. (See 5.1.4.) | 


In addition, generate an ICAM network that supports unsolicited ouput. For more details, see 
the IMS system support functions user guide/programmer reference, UP-8364 (current 
version). 


5.3.2. DLMSG (Displaying the Last Effective Output Message) 


When the cold or warm start-up option is specified at IMS 90 initiation, IMS 90 appends 
the transaction code DLMSG to the IMS READY message. By pressing the transmit key, 
each terminal operator can retrieve the last valid output message in the terminal output 


message file (TOMFILE) for the terminal. This determines how far rollback of the files — 


accessed by that terminal has gone so that production can be appropriately resumed. 


The same transaction code, DLMSG, can be entered during online operations to display 
the last “effective’’ output message at the origining terminal; i.e., all updates performed 
since the output message was first generated (if any) have since been rolled back or can 
be rolled back. 


The DLMSG transaction code can be transmitted with a configured terminal-id as a 
following operand. This retrieves the last valid message output at the specified terminal 
and displays it at the originating terminal. 


The format of the DLMSG transaction code is: 


DLMSG[Aterminal-id] 
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where: 


terminal-id 
Is the configured symbolic identification of the specified terminal. 


If the named terminal cannot be found in the terminal control table (TCT), the following 
diagnostic is issued to the originating terminal: 


INVALID TERMINAL-ID 


If no message is found in the TOMFILE for the named terminal, the following message is 


issued: 
SUBFILE IS EMPTY 


lf an I/O error occurs while the TOMFILE is being read, the following diagnostic message 
is issued: | 


**** 1/Q ERROR ON TOMFILE **** 


**** NO MESSAGE RETRIEVED **** 


5.3.3. DLOAD (Downline Loading a UTS 400 Program) 


The IMS 90-supplied downline load action program, ZUKLOD, enables users to downline 
load UTS 400 programs from the IMS 90 load library to a UTS 400 terminal. ZUKLOD is 
activated by the transaction code DLOAD. The format is: 


DLOAD program-name[,aux-device-no,prog-id] | 


where: 


program-name ; 
Is the 8-byte name of the load module to be downline loaded. 


aux-device-no 
Is the auxiliary device number of the auxiliary storage device (cassette or diskette 
subsystem). This number must be between 1 and 9 inclusive. 


prog-id 
Is the name of the program being downline loaded to either a cassette or a 
diskette. Only alphanumeric characters (A through Z and O through 9) may be 
used. Prog-id may be a maximum of 4 characters long. 


The optional entries are used for downline loading to a peripheral device. If these optional 
entries are not used, the default loading is directed to the UTS 400 memory. 
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© On initial activation, the ZUKLOD action program issues the function call, SETLOAD. The 
SETLOAD function prepares a work area defined within the CDA for use by the GETLOAD 
function. Following the call to the SETLOAD function, ZUKLOD calls the GETLOAD 
function, which provides a block of code from the UTS 400 program load module. This 
code is prefixed with proper header information and sent as an output message to the UTS 
400 terminal using the continuous output feature with external succession. The same 
action program (ZUKLOD) is rescheduled to continue issuing GETLOAD functions. 


5.3.3.1. Downline Load to Main Storage 


After the last block of code is sent to the UTS 400 terminal, the terminal transmits a 
response message indicating whether or not the downline load was successful. After 
ZUKLOD terminates normally, a message is displayed indicating the success or error of 
downline loading. These messages are listed in Table 5-3. All messages are displayed at 
the UTS 400 terminal requesting the downline load except DELIVERY NOTICE ERROR, 
which is displayed at the IMS 90 master terminal. 


NOTE: 


lf the UTS 400 program is to be executed directly after a successful downline load, it is 
responsible for capturing the successful load message at the UTS 400 entry point 
‘TEXTCM’. If the UTS 400 program does not consider this entry point, the master or 
primary screen and file control characters will be cleared and the successful load message 
displayed. 





Table 5—3. ZUKLOD Action Program Messages 


a 


| DELIVERY NOTICE ERROR ON UTS 400 | An error occurred when the operator tried to send a block of data to the UTS 
TERMINAL: nn 400. The letters nn represent a two-character hexadecimal delivery notice error 
code. (See Tables 3-19 and 3-20 for a description of the error code.) 



















LOAD ERROR ENCOUNTERED FROM 





A host system read error has occurred, reading a block of data from the load 
library. nn = system loader error code. See OS/3 system messages 
programmer/operator reference, UP-8076 (current version). 
















SUCCESSFUL LOAD 





The program has loaded successfully. 








UTS 400 LOAD ERROR BIT(S) n [&n] 





INVALID CHARACTER IN OFFLINE Only alphanumeric characters A through Z and O through 9 are allowed for 
name of program being downline loaded to a cassette/diskette. Reenter the 


DLOAD transaction code using corrected program name. 






5.3.3.2. Downline Load to Auxiliary Storage Device 


Unlike a downline load to main storage, the UTS 400 terminal does not generate a 
response message after the last block of code is sent to the auxiliary storage device. 
Hence, the status of the downline load is not known until the-program is read from the 
auxiliary storage device into main storage. 
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5.3.4. ZSTAT (Displaying Statistical Information) © 


The ZSTAT transaction displays the current status of all files, programs, transactions, and 
terminals in an IMS 90 network. If you use the 7/7 PARAM RESTART statement at IMS 90 
Start-up time (for multithread only) after you have previously shut down normally, you can 
accumulate these same statistics for multiple sessions. 


You can enter the ZSTAT transaction code only from a configured master terminal. You 
can't use ZSTAT in a single-thread system in which the console is the master terminal. 


When using ZSTAT on a UTS 400 device, you must enter VAR on the control page 
transmit function, XMIT, to indicate transfer of all variable information and field control 
characters associated with the variable data. Also, you must set the FCC/PROTECT switch 
to the FCC position. | 


Issue the ZSTAT transaction code in the following format: 


ZSTATP(ALL [,CONT] [,AUXn] sae: 
fee 


where: 
Is the auxiliary device identification. ® 


Is the cassette/diskette track address. 


ssss 
Is the cassette/diskette starting position. 


You can issue the ZSTAT transaction code in three ways: 


1. The ZSTAT ALL [,CONT] [,AUXn] [,TCSassss] format allows a choice of displaying 
Statistics for all files, programs, transactions, and terminals in noncontinuous or 
continuous output modes to the primary output device and the auxiliary output device. 
When using continuous output and an auxiliary device, you must configure 
CONTOUT=YES. If ZSTAT ALL is entered without the optional parameters, 
noncontinuous output mode is assumed and the output is displayed on the primary 
device only. 


2. The ZSTAT HELP format displays the ZSTAT parameters with an explanation of each 
on the primary device only. You can then either terminate or continue processing 
ZSTAT. 


3. The ZSTAT transaction code entered alone at the terminal displays a menu which 
allows you to select the statistical information you desire and indicate continuous 
Output and an auxiliary device number ID. 
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Because ZSTAT produces a menu screen that contains protected fields, only display 
devices that have a screen protection feature can use the menu form of the ZSTAT 
transaction code. Hard copy devices or display devices not having the screen protection 
feature can only use the ZSTAT ALL form of the transaction code. 


When you enter ZSTAT ALL, the resulting output is a display of all the current files, 
programs, transactions, and terminals in the IMS 90 network. Each of these items starts a 
new page of output. Figures 5-1 through 5-4 show sample noncontinuous mode output 
displays for each item. The ZSTAT format does not produce menu screen output. 
Therefore, if you wish to indicate continuous output and an auxiliary device ID, you must 
enter the CONT and AUXn parameters with the ZSTAT transaction code. If the auxiliary 
device is a cassette or diskette, the TCS parameter must follow the AUX parameter. 
The file status display contains the following information: 
a File name (maximum of 13 eight-character names) 
= File status 

- OPEN 

- CLSD (CLOSED) 


- JS INVALID 
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m @€=s- File type 





- MRAM (MIRAM) 
- ISAM 
- DAMR 


- SAM 





- SAT 

~ PRNT (batch printer file) 
= Number of file accesses 
= Number of file updates 


= Total number of accesses and updates for all files. 












[MORE ] 79/88/28 17:85:32 
FILE STAT TYPE ACCESSES UPDATES 










FILE] OPEN MRAM 15 3 
FILE2 CLSD SAM 936 772 
FILE3 OPEN SAM 842 624 
FILE4 1S INVALID 

FILES CLSD 1SAM 2879 1192 
FILES CLSD DAMR 1988 293 





TOTALS 4952 2884 





Figure 5—1. Sample File Status Display 


The program status display gives the following information: 
= Program ne 
a Program status 

- UP 


- DOWN 


© - IS INVALID 
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Program type 


—-  RE-ENT 
- SERIAL 


- SHARED (multithread only) 


Resident program 


- YES 


- NO 


Subprogram 


- YES 


- NO 


Number of program accesses 
Number of program loads 


Total number of accesses and loads for all programs 


(MORE ] 
PROGRAM STAT TYPE RES SUB 
PROGRAMI UP SHARED YES YES 
PROGRAM2 DOWN RE-ENT YES NO 
PROGRAM3 UP RE-ENT YES NO 


PROGRAM4 UP SERIAL NO NO 
TOTALS 


Figure 5—2. Sample Program Status Display 


transaction status display information includes: 
Transaction name 

Transaction status (IS INVALID) 

Number of transaction accesses 


Total number of accesses for all transactions 


79/08/28 
ACCESSES 


9169 


351 
72 


9523 


5-24 
Update A 


17:86:15 
LOADED 


5199 


72 
5172 
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[MORE ] 79/88/28 17:85:32 
TRANSACT ACCESSES 


TRNS1 98 
TRNS2 1239 
TRNS3 4789 
TRNS4 [IS INVALID 


TOTALS 













6869 


Figure 5—3. Sample Transaction Status Display 


Terminal information in the terminal status display is: 
= =Terminal ID 
= Terminal status 

_ DNP(physically down) 

-  DNL(logically down) 


-  HLD(hold mode) 





-  TMD(test mode) 
- UP 
= Current transaction code 
2 Alternate terminal identification (if any) 
= Number of input messages processed by this terminal during the current session 
= Number of output messages sent to this terminal during the current session 
= Number of transactions executed by this terminal during the current session 
=» Number of terminal commands executed at this terminal during the current session 


2 Total number of slots available (for global networks only) or number of additional 
terminals that will be allowed to sign on via $SSON command 


= Total number of input messages for all terminals with active sessions 
= Total number of output messages for all terminals with active sessions 
@ = Total number of transactions executed for all terminals with active sessions 


is Total number of terminal commands executed for all terminals with active sessions. 
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[MORE ] 88/86/05 98:25:63 
TERM STAT TRANSCODE ALT IN-MSGS OUT-MSGS TRANSACTS COMMANDS 


TRMB UP ZSTAT TRM1 199 95 33 185 
TRM1 DNP 6 bs) ) | 
TRM2 HLD 29 8 7 8 


TOTALS 3 SLOTS 126 168 45 114 




















Figure 5—4. Sample Terminal Status Display 


ZSTAT HELP keyed in at the terminal first displays the ZSTAT positional parameters and 
their meaning. (See Figure 5-5.) 









ZSTAT POSITIONAL PARAMETERS 
ALL - A STATUS REPORT FOR THE FILES, PROGRAMS, TRANSACTIONS AND TERMINALS 
,CONT —- SPECIFIES CONTINUOUS OUTPUT MODE. 

( CAN ONLY BE USED WITH THE ALL PARAMETER) 
,AUXN - SPECIFIES OUTPUT TO THE PRIMARY DEVICE AND AUXILIARY DEVICE N. 
( CAN ONLY BE USED WITH THE ALL PARAMETER) 
,TCSASSSS - SPECIFIES OUTPUT TO PRIMARY AND CASSETTE/DISKETTE 
(A 1S TRACK ADDRESS, SSSS IS START POSITION OF CASSETTE/DISKETTE) 
1F NO POSITIONAL PARAMETERS ARE SPECIFIED, THE OPERATOR WILL RECEIVE A MENU 
SCREEN TO SOLICIT STATISTICAL INFORMATION REQUIRED. SEE NEXT PAGE FOR 
KEYWORD AND VALID INPUTS. 












NEXT PAGE YES 7D NO 






Figure 5—5. Sample ZSTAT HELP Output Screen Display, Page 1 
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To respond YES, press TRANSMIT. The second HELP screen then displays the choice of 
keyword parameter values available for each status display. (See Figure 5-6.) To respond 
NO, press TAB and then TRANSMIT. 














KEYWORDS AND VALID INPUTS 
FILES=NONE/ALL/OPEN/CLOSE/NAME-LIST 
PROGRAMS=NONE/ALL/NAME-LIST 

TRANSACTIONS=NONE/ALL/NAME-LIST 
TERMINALS=NONE/ALL/INT/NAME-LIST 

NONE : NO STATISTICAL INFORMATION REQUESTED (DEFAULT IF BLANK) 
OPEN : STATISTICAL INFO. FOR OPEN FILES ONLY 

CLOSE : STATISTICAL INFO. FOR CLOSED FILES ONLY 

INT : STATISTICAL INFO. FOR INTERACTIVE TERMINALS ONLY 

ALL : STATISTICAL INFO. FOR ALL ITEMS OF THE GIVEN FUNCTION 
NAME-LIST : STATISTICAL INFO. FOR THE SPECIFIED NAMES ONLY 
CONTINUE PROCESSING ZSTATCYESDNO 








Figure 5—6. Sample ZSTAT HELP Output Screen Display, Page 2 


If you respond YES at the end of the second HELP screen, the menu screen is displayed. 
(See Figure 5-8.) 


lf ZSTAT is keyed in with no other parameters, a menu screen is displayed for soliciting 
further information. (See Figure 5-7.) This menu allows you to specify the parameters you 
‘want for files, programs, transactions, and terminals in addition to continuous output and 
auxiliary device number ID. When ready to enter the keyword parameters, continuous 
output reply, or auxiliary device ID number on the screen, you can arrive at the space 
following each equal size or question by pressing the tab key. Do not use the carriage 
return key (CR) or space bar when skipping from field to field. Instead, use the TAB key. 












FILES= 
PROGRAMS= 
TRANSACTIONS= 
TERMINALS= 


CONTINUOUS OUTPUT (REPLY Y/N AT UNDERLINE) ?_ 
AUX DEVICE 1D NUMBER (REPLY AT UNDERLINE)? 
IF CASSETTE/DISKETTE, ENTER TRACK ADDRESS & STARTING POSITION? 






Figure 5—7. ZSTAT Menu Output Screen 
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You enter a parameter value for each item on the menu including a response to the 
continuous output and auxiliary device question. The parameter values for each item on 
the menu follow: 





a 


N 
CLOSED 

ALL 
file-name-list 


PROG my NORE 





Mad 
— : | 


eae ateteteSee t 
ab 3 






| 





TERMINALS=(#ONE 
INT 
ALL 
term-name-list 
where: 
NONE 


Means no statistical information requested. 


OPEN 
Means information is requested for open files only. 


CLOSED 
Means information is requested for closed files only. 


ALL 
Means information for all files, programs, transaction, or terminals is requested. 


name-jist 
Requests information for the files, programs, transactions, or terminals named in 
the list. A name cannot be split across two lines. 

INT 


Requests information for interactive terminals only. 


Means continuous output is requested. 





Means no continuous output is requested. 


Means supply a 1-digit auxiliary device ID number. 
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Figure 5-8 illustrates a sample menu input screen. As a result of entering choices on the 
menu screen, you receive status displays similar to Figures 5-1 through 5-4. This ZSTAT 
format allows you to be more selective of status information. Also, note that when you 
make errors in spelling on the menu (e.g., FLIE4) you will receive an invalid message in 
your resulting status display. (See Figure 5-1.) 


NOTE: 


You may enter a maximum of 13 eight-character file names and 13 eight-character 
program names, 18 five-character transaction codes, and 22 four-character terminal 
names. 











FILES=FILEL,FILE2, FILE3,FLIE4, FILES, FILES 
PROGRAMS=PROGRAM1, PROGRAM2 , PROGRAM3 , PROGRAM4 
TRANSACTIONS=TRNS1,TRNS2,TRNS3,TRNS4 
TERMINALS=ALL 
CONTINUOUS OUTPUT? (REPLY Y/N AT UNDERLINE) Y¥ 


AUX DEVICE 1D NUMBER (REPLY AT UNDERLINE) 3 
IF CASSETTE/DISKETTE. ENTER TRACK ADDRESSS & STARTING POSITION?..__.. 


Figure 5—8. Sample Menu Input Screen 


5.3.4.1. Controlling the Terminal 





When continuous output is used, the terminal operator usually does not have control of 
the terminal except in two cases: | 


1. when ICAM detects an error from the auxiliary device and returns an error delivery 
notice to ZSTAT and ZSTAT sends an error message to the primary device; or 
2. when you press function key 1, 2, 3, or 4 during processing to interrupt continuous 


output of statistics 
Table 5-4 indicates the functions performed when one of the function keys is pressed. 


Table 5—4. Responses to Interruptions of ZSTAT 


Master Terminal Entry Function Performed 


Transmit Key Continue processing output messages. 
Function Key 1* Break processing and prompt terminal operator again. 


Function Key 2* Resume processing. ZSTAT reinitializes itself to its state before interruption and 





retransmits the previous message's output status message. 


Function Key 3* End of processing; ZSTAT terminates. 
@ Function Key 4* Resume processing at next function. 


ZSTAT (with optional ZSTAT starts again. 
parameters, if any) 


*Key in F#01, F#02, F#03, or F#O4 if no function key is available. 








UP-8614 Rev. 1 SPERRY UNIVAC OS/3 5-30 
IMS 90 APPLICATIONS Update A 


When you press function keys, IMS 90 accepts from ICAM either the function key code or 
the delivery notice (whichever comes first) and passes the first accepted code to ZSTAT via 
the IMA. Repeated use of the function key eventually produces the results needed by 
ZSTAT. 





Any other replies to an interruption of continous output causes the message INVALID 
RESPONSE, PLEASE TRY AGAIN to be sent to the primary device. 


These function key responses are also valid in noncontinuous output mode. When a user 
types in ZSTAT ALL with noncontinuous output, the only way the user can stop the ZSTAT 
transaction from giving all the status information is by using function key 3 to terminate or 
function key 4 to resume at the next function. 


5.3.4.2. ZSTAT Error Messages 


ZSTAT generates error messages when ICAM returns an error delivery notice. To 
determine which error message to issue, ZSTAT tests the specific ICAM delivery notice. If 
ZSTAT receives an unrecognizable delivery notice, a snap dump is generated in which the 
OMA contains the message UNRECOGNIZED DELIVERY NOTICE, and a transaction 
termination message is sent to the source terminal. If this problem occurs, you should 
contact your local Sperry Univac representative. 


Tables 5-5 and 5-6 show ZSTAT recoverable and nonrecoverable error messages and 
explain their causes and responses. © 


Table 5—5. ZSTAT Recoverable Error Messages (Part 1 of 2) 


READY GOOD STATUS BUT TERMINAL PRINTER lf F2* or F4* is entered, ZSTAT tries to resend the original 
WRITE FUNCTION INOPERATIVE REPLY F2 OR message. If F3* is entered, ZSTAT terminates. 
F4 (RESUME) OR F3 (END) . 


TERMINATE PRINTER OUT OF PAPER, 
INOPERATIVE, OR IN TEXT MODE REPLY 
F2 OR F4 (RESUME) OR F3 (END) 


DEVICE NOT RESPONDING - MAY BE 
DISCONNECTED REPLY F2 OR F4 (RESUME) 
OR F3 (END) 


DISK ERROR - REPLY F2 OR F4 (RESUME) 
OR F3 (END) 


NO ICAM NETWORK BUFFERS AVAILABLE - lf F2* or F4* is entered, ZSTAT tries 15 more times to output a 
REPLY F2 OR F4 (RESUME) OR F3 (END) terminal status message and then prompts the user again. If 
F3* is entered, ZSTAT terminates. 


01 CONTINUOUS OUTPUT NOT CONFIGURED. DO The user requested continuous output mode but the CONT 
YOU WISH TO CONTINUE USING parameter was specified without the CONTOUT=YES parameter 
NONCONTINUOUS OUTPUT (Y/N)? in the configurator OPTIONS section. 





*F2, F3, and F4 are abbreviations for function key 2, 3, or 4; thus, a reply of F2, F3, or F4 means press function key 2, 
3, or 4 at the terminal. 
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Table 5—5. ZSTAT Recoverable Error Messages (Part 2 of 2) 


02 AN AUXILIARY DEVICE WAS REQUESTED The user requested an auxiliary device without the 
AND NOT CONFIGURED. DO YOU CONTOUT=YES parameter in the configurator OPTIONS section. 
WISH TO CONTINUE WITHOUT AN 
AUXILIARY DEVICE (REPLY Y/N)? 





03 AUX-DEVICE ID INVALID, PLEASE INPUT The user keyed in an invalid auxiliary device ID. The correct 2- 
VALID ID P17 - digit numeric auxiliary device ID must be entered. 


04 INVALID TRACK ADDRESS. PLEASE The track address for cassette/diskette is invalid. Enter the 
INPUT VALID TRACK ADORESS P - correct address. 


O5 INVALID STARTING POSITION. The starting position for cassette/diskette is invalid. Enter a 
PLEASE INPUT VALID STARTING correct starting position. 
POSITION > ---- 





Table 5—6. ZSTAT Unrecoverable Error Messages 


NOT MASTER TERMINAL ZSTAT was not issued from the master terminal. 


INVALID INPUT PARAMETER] One of the ZSTAT positional parameters is incorrect in the ZSTAT ALL format. 
Auxiliary device number is invalid or CONTOUT=YES was not configured but was 
requested. 





DATA ERROR ON TCS An error was found while data was being sent to the cassette/diskette. Retry ZSTAT. 
lf failure persists, check the condition of the cassette/diskette and associated 
hardware. 


CASSETTE/DISKETTE NOT The cassette/diskette device was not powered up and in the ready state. The user 


RESPONDING. ZSTAT should check the hardware device. 
TERMINATED | 





5.4. GLOBAL NETWORK TERMINAL COMMANDS 


IMS 90 can interface ICAM global networks. After you configure IMS 90 and write the 
global network definition, IMS 90 at start-up issues ICAM macros to attach IMS 90 to the 
global network you described. Once this interface exists, without redialing, a terminal 
operator can attach his terminal to IMS 90. This terminal-to-IMS 90 interface is called a 
dynamic session. The terminal operator initiates a dynamic session by keying in: 


$$SON terminal-idprogram-name 
where: 
terminal-id 
7 ls the terminal name specified on the label of the TERM macro in the network 


definition. 
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program-name © 


Is the name of the IMS 90 program specified on the label of the LOCAP macro in 
the network definition. No space is permitted between terminal-id and program- 
name. 


Example: 


$$SON TRMLIMS9 


After issuing the $SSON command, the terminal operator receives the following 
responses: 


SPERRY UNIVAC DCA NETWORK, LEVEL n.n NODE ID xxxx 
SESSION PATH OPEN (after session is initiated) 
or 


SESSION PATH CLOSED (if the session is rejected) 


SESSION PATH OPEN means that you have successfully signed onto IMS 90. Note that 

the SESSION PATH OPEN is used instead of the IMS READY message. SESSION PATH 

CLOSED means that the sign-on was unsuccessful. This could be because IMS 90 was not | 
loaded into the system or IMS 90 itself did not have enough terminal resources to accept © 
the sign-on command; the terminal tables within IMS 90 could not accommodate another 

terminal. These terminal resources are controlled by the TERMS keyword in the 
configurator NETWORK section. 


To terminate the dynamic session and detach the terminal from the IMS 90, the terminal 
operator issues the following command: 


SSSOFF 
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6. Transaction Processing via UNIQUE 


6.1. UNIQUE CONCEPT 


The uniform inquiry update element (UNIQUE) is a set of action programs provided by 
Sperry Univac that perform file retrieval and updating functions through the use of 
commands from the terminal. 


UNIQUE accesses data files through defined record management (DRM). Thus, the user 
must define the data structure (files, records) and the allowable operations (retrieve, | 
modify, add, delete) by submitting a data definition for each defined file to the data 
definition processor. (See Section 2.) 

& IMS 90 provides a password capability for UNIQUE users through both the data definitions 
processor and the PASSWORD function parameter of the NAMEREC file utility. Access to 
defined files and subfiles can be restricted to specific terminals by means of the 


NAMEREC utility which is described in detail in the IMS 90 system support functions user 
guide/programmer reference, UP-8364 (current version). | 


6.1.1. UNIQUE Dialog 

A UNIQUE dialog consists of a series of commands and responses dealing with a 
particular defined file. Dialogs with different defined files can be combined to form a 
UNIQUE transaction. 7 7 | 

The response to a UNIQUE command is based on: 

= the command itself; 

= additional text in the eanmiane message; 

= the contents of the file being accessed; and 

= the previous conning ieeeesen acing this dialog. 


-< The actual words used in a dialog comprise the UNIQUE lexicon. (See Appendix B.) The 
& UNIQUE syntax is described in the examples supporting the command explanations. 





UP-8614 Rev. 1 SPERRY UNIVAC 0S/3 6-2 
IMS 90 APPLICATIONS 


UNIQUE uses the following commands: & 
=» OPEN 
Initiates a dialog with a defined file. The initial OPEN command, or an OPEN 
- command issued after a CLOSE command. (or after the ZZCNC terminal command), 
functions as a transaction code and initiates a UNIQUE transaction. A subsequent 
OPEN command starts a new dialog with a different defined file but does not initiate 
a new transaction. 
# CLOSE 
Terminates a transaction. 
s DISPLAY 
Causes a specified record to be displayed at the terminal. 


ea LIST 


Displays certain records or parts of records at the terminal; can also display the 
results of statistical functions. | 


a DETAIL 


Interrupts the processing of the previous LIST command to obtain a different or more 
detailed listing. 


» SHOW 


Displays the format of the defined file being accessed and the most recent LIST, 
DETAIL, ADD, DISPLAY, DELETE, and CHANGE commands. 


= MORE 


Requests the next screenful of information according to the previous LIST, DETAIL, or 
SHOW command. 


# ADD 

Enables the terminal operator to add a record to the file. 
= CHANGE 

Enables the terminal operator to change values in a record. 
me DELETE 


Displays a specified record, which can then be deleted by keying in the OK command. © 
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@ - « 


Completes the function indicated by the previous command -— ADD, DELETE, or 
CHANGE. 


# CANCEL 


Cancels the most recent (current) update command - ADD, DELETE, or CHANGE. 


ae NEXT 


selects the next identifier from the most recent DISPLAY, ADD, CHANGE, or DELETE 
command and performs the same function. 


6.1.2. Defined Files Accessed by UNIQUE 


The defined files partially shown in Figures 6-1 and 6-2 are referenced in the discussion 
of UNIQUE commands that follows. The STATES file is a simple defined file; the TOWNS 
file is a hierarchical defined file. 


The file listings presented in both illustrations correspond to the format used by UNIQUE 

when displaying records in response to the LIST command. The asterisk (*) indicates a 

header line containing names that serve as column headers. The period (.) indicates a 
© detail line containing values stored in the file. 


Each record in the STATES file contains the name of the state, the state population, and 
the capital city. The name of the state serves as the record identifier. 












“STATE STATE-POP CAPITAL 














ALABAMA 3,444,165 MONTGOMERY 
ALASKA 362,173 JUNEAU 
ARIZONA 1,772,484 PHOENIX 
ARKANSAS 1,923,299 LITTLE ROCK 
CALIFORNIA 19,953,134 SACRAMENTO 
COLORADO 2,207,259 DENVER 
CONNECTICUT 3,932,217 HARTFORD 
DELAWARE 598,164 DOVER 
FLORIDA 6,789,443 TALLAHASSEE 
GEORGIA 4,589,573 ATLANTA 


Figure 6—1. Partial Listing of STATES File 
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Three types of records comprise the TOWNS file: state, county, and town records. Figure 
6-2 represents these records as displayed in response to a LIST command. The state 
record contains the name of the state, the governor, and the capital city. For each state 
record, there are one or more county records for each county record, one or more town 
records. The county record contains the name of the county and the county seat. The town 
record contains the town name, the mayor’s name, and the population. 


" STATE GOVERNOR CAPITAL 
" -COUNTY COUNTY-SEAT 
-- TOWN MAYOR POPULA 
. ALABAMA WRIGHT ,GEORGE MONTGOMERY 
-BREWSTER RIVERTON 
- LEWIS BROWN, HENRY , 746 
--MOREHEAD ARCHER, ROBERT 358 


--RIVERTON JOHNSON,ALAN ,623 
--WINSLOW — TURLEY, PAUL ,175 
-CARSON ~ HOWELL 

-- HOWELL SMITH, FRANKLIN 7,968 
-- SCHUYLER LAWSON, PHILLIP ,482 
-CLARK HICKSVILLE 





Figure 6—2. Partial Listing of TOWNS File 


Each record in a file has an identifier. Records are ordered on these identifiers. The 
identifier of the first record in the STATES file (Figure 6-1) is ALABAMA, the second is 
ALASKA, etc. The first record in the TOWNS file (Figure 6-2) is a state record and its 
identifier is ALABAMA. The identifier of the second record (the first county record) is 
ALABAMA, BREWSTER; the third, a town record, is ALABAMA, BREWSTER, LEWIS. 


Notice in the county records shown in Figure 6-2 (BREWSTER, CARSON, CLARK) that the 
ALABAMA is replaced by a hyphen (-). This serves to reduce the amount of space occupied 
on the screen. Similarly, the ALABAMA, BREWSTER part of each town record's identifier 
is replaced by two hyphens (- -). 


Note that when UNIQUE adds or changes a defined record, it sets the sign of any new 
value for a packed decimal item to hexadecimal F instead of C. 


6.2. UNIQUE COMMANDS 


The data manipulating commands provided by UNIQUE, with examples of their use, are 
described in 6.2.1 through 6.2.13. The examples intentionally follow in succession as in a 
stream of commands and are numbered consecutively throughout the discussion. In order 
to highlight each new input or output message in the examples, previously issued 
commands and responses remaining on the screen are shaded. 
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@ The format for most commands is the same whether the input is on a display device or a 

hard copy device. The examples given with these commands are for a display device. The 

formats for the ADD and CHANGE commands, however, vary for display and hard copy 

devices. Both formats, their parameters, and examples of their use are provided for these 
commands. | 8 


When keying in UNIQUE commands at the terminal, the following general rules apply. 
Specific rules for individual commands are noted where applicable. | 


1. Parameters are separated from the UNIQUE command and from each other by spaces. 

2. In identifiers, values, and specifications, alphanumeric item-names and literals 
containing blanks or special characters must be enclosed by apostrophes. These 
special characters include comma (,), semicolon (;), leading hyphen (-), and apostrophe 
(‘). By convention, the apostrophe is represented by a pair of apostrophes if it is used 
as a character in an item. For example, the value O'Brien would be entered as 
‘O'Brien’. | 


3. Numeric literals must not be enclosed by apostrophes. 


4. Decimal points and commas must appear where appropriate in numeric values. 


6.2.1. OPEN 

© The OPEN command denotes the beginning of a UNIQUE dialog and designates the 
password of the file that the user intends to query or update during this dialog. This 
command can be issued at any time during a transaction to access a different file. Issuing 
another OPEN command during a transaction does not initiate a new transaction but starts 
a new dialog with a different file. 


The OPEN command and one other UNIQUE command can be transmitted together to 
improve throughput. (See example 2.) 


Format: 


OPEN password 


where: 


password - | 
Is an alias for a defined file or is the actual defined file or subfile name defined 
by the data definition processor. 









UP-8614 Rev. 1 SPERRY UNIVAC OS/3 6-6 
IMS 90 APPLICATIONS 





Example 1: 


Input 


OPEN STATES 





Output 





OPE ETE 77/12/27 15:47:89 


The OPEN command initiates the transaction and makes the STATES file accessible to 
the terminal operator. 


Example 2: © 


Input 


OPEN STATES 


DISPLAY ALASKA 





Output 


STATE STATE-POP CAPITAL 





In this example, the OPEN command transmitted opens the STATES file and displays @ 
the first state record (ALASKA). The OPEN COMPLETE message is not sent to the 
terminal. 
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6.2.2. CLOSE 


The CLOSE command terminates the UNIQUE transaction. No UNIQUE commands are 
then recognized until another OPEN command is issued. 


Format: 
CLOSE 
NOTE: 


The CLOSE command is not required to terminate a dialog. Issuing another OPEN 
command terminates access to the file, then immediately provides access to the new file. 


Example: 


Input 


CLOSE 


Output 


CLOSE COMPLETE 77/12/27 15:48:15 





6.2.3. DISPLAY 

The DISPLAY command causes the specified record to be displayed at the terminal. 
Column headings, as well as values, are displayed. The column headings are obtained 
from the IDENTIFIER and ITEM statements of the data definition. 


Format: 


DISPLAY identifier-1 [;identifier-2]... 
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where: 


identifier-1 
Indicates a specific record. Hyphens (--) are used as ditto characters when 
portions of an identifier are repeated in a subsequent identifier or a subsequent 
command. (See example 2.) 


identifier-2 
Designates another record. This record is not displayed, however, unless the 
NEXT command follows this DISPLAY command. 


In response to a DISPLAY command, UNIQUE displays the record specified by the first 
identifier. If more identifiers are specified in the DISPLAY command, the records 
corresponding to the other identifiers are displayed, one at a time, by using the NEXT 
command. The DISPLAY command and ensuing NEXT commands can be mixed with other, 
intervening commands that do not alter the effect of the NEXT command. Other 
commands that can appear prior to the NEXT command are LIST, MORE, DETAIL, or 
SHOW. 


Example 1: 


Input 


OPEN TOWNS 


DISPLAY ALABAMA, CARSON 





Output 


MASTERY SER un 
COUNTY COUNTY - SEAT 
ALABAMA,CARSON HOWELL 





The DISPLAY command presents the data from the record identified by 
ALABAMA,CARSON in the TOWNS file. 
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Example 2: 


Input 


DISPLAY --SCHUYLER 





Output 


MAYOR POPULA 
ALABAMA ,CARSON, SCHUYLER LAWSON, PHILLIP 11,482 





The terminal operator uses the _ ditto characters (--) to indicate that 
ALABAMA,CARSON from the previous DISPLAY should be used for the first part of 
the town identifier. 


It is not necessary to issue another OPEN for the TOWNS file. The OPEN from 
exampie 1 ts still in effect. 


Example 3: 


Input 


OPEN STATES 
DISPLAY ALASKA; FLORIDA 





Output 


STATE. STATE-POP. CAPITAL 
ALASKA 302,173 JUNEAU | DNEXTT 
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The OPEN causes UNIQUE to close the TOWNS file and allow access to the STATES @ 
file. The DISPLAY command requests UNIQUE to display the information from the 

record whose identifier is ALASKA. The embedded NEXT command is the result of 

multiple identifiers in the DISPLAY command. To display the record associated with 

the next identifier, FLORIDA, the operator presses the TRANSMIT key. If the 
embedded NEXT command is not transmitted at this time, it can be specified later, as 

long as a DELETE, ADD, or CHANGE command (or another DISPLAY) does not 
intervene. 


6.2.4. NEXT 

The NEXT command selects the next identifier from the most recent DISPLAY, DELETE, 
ADD, or CHANGE command. The function performed on the identified record is determined 
by that previous command. 


Format: 


NEXT 
Example 1: 
Input 


NEXT 


Output 


STATE STATE-POP CAPITAL 
FLORIDA 6,789,443 TALLAHASSEE 





The preceding command was DISPLAY ALASKA; FLORIDA. Since the ALASKA record 
already has been displayed, NEXT requests the display of the FLORIDA record. 
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Example 2: 


input 





Output 


DISPLAY COMPLETE 79/12/27 15:49:23 





There are no more identifiers outstanding from the previous DISPLAY command; 
therefore, the DISPLAY COMPLETE message is sent. 


6.2.5. DELETE 


The DELETE command gives the terminal operator the ability to delete a record after 
viewing the information in the record. UNIQUE displays the specified record in response to 
the DELETE command. To effect the deletion, the terminal operator must key in the OK 
command. If he decides not to delete the record, he should key in the CANCEL command. 


Format: 


DELETE identifier-1 [:;identifier-2]... 


where: 


identifier-1 
Designates a specific record. Ditto characters (--) can replace portions of the 
identifier. 


identifier-2 
Designates another record in the file. This record is displayed when the NEXT 
command is specified. 


The DELETE command places the terminal in an update state. While the terminal is in this 
state, no other UNIQUE commands are accepted except OK or CANCEL. The following 
example illustrates. 
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Example: 


Input 


DELETE DIST/COLUMBIA 





Output 





| STATE-POP CAPITAL 
DIST/COLUMBIA 756,518 





The item CAPITAL for this record has no value. 


6.2.6. OK 

The OK command executes the function associated with the previous command. It is used 
only with the DELETE, ADD, or CHANGE command. Upon successful completion of that 
function, UNIQUE establishes a new rollback point for the current transaction. 


Format: 


OK 


Example: 


Input 
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Output 





DELETE COMPLETE 77/12/27 15:53:23 





Because the previous command was DELETE, the OK command requests UNIQUE to 
perform the deletion of the DIST/COLUMBIA record. 


6.2.7. CANCEL 


The CANCEL command requests UNIQUE to cancel the previous update command 
(DELETE, ADD, or CHANGE); thus, the file remains as it was before that update command. 


Format: 


CANCEL 


Example: 





Input 


DELETE ALABAMA; ALASKA 





Output 


STATE- POP CAPITAL 
ALABAMA 3,444,165 MONTGOMERY 
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Input 


CANCEL 


Output 


DELETE CANCELED 77/12/27 15:55:84 DNEXT 





This sequence of inputs and outputs results in no change to the file. The terminal 
operator now can enter NEXT to initiate the delete sequence for the ALASKA record. 


6.2.8. ADD 


The ADD command initiates a series of inputs and UNIQUE responses by which a record 
can be added to the file. There are two formats for this command - the display format and 
the hard copy format. 


When using the IBM 3270 display station under UNIQUE, your command input or 
responses to UNIQUE messages must be in hard copy format rather than display format. 
The reason for this is the IBM 3270 display station transmits a whole screen of data to the 


UNIQUE program instead of a data field limited by a start-of-entry ( > ) symbol and the 
cursor. 


Upon successful completion of the ADD function, UNIQUE establishes a new rollback point 
for the current transaction. 


The ADD command places the terminal in an update state. While the terminal is in this 
state, no UNIQUE commands are accepted except OK or CANCEL. 


6.2.8.1. Display Format 
Format: 

ADD identifier-1l[;identifier-2]... 
where: 

identifier-1 


Is the record designation. Ditto characters (--) can replace portions of the 
identifier. 
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identifier-2 | 
ls another record designation. The update format for this record is displayed 
when the NEXT command is entered. 





In response to the ADD command, UNIQUE sends to the terminal the item names (column 
headers) and update formats of the items associated with the specified record. The 
terminal operator can depress the tab key to advance the cursor to the beginning of each 
update format. (Note that an extra character position is provided for the sign of numeric 
items.) The terminal operator overwrites the update formats with values and then 
transmits the modified screen. If UNIQUE finds no errors, it adds the new record to the file 
and sends an ADD COMPLETE message to the terminal. If errors are discovered, UNIQUE 
sends the column headers, update formats, and either valid values or error notations back 
to the terminal for further modification by the terminal operator. 


At any time during this sequence, the terminal operator can key in the CANCEL command 
instead of overwriting the update formats with values. The ADD command is then 
canceled. 


Example 1: 


Input 





ADD DIST/COLUMBIA 





Output 


Sgttere ee 


STATE-POP CAPITAL 
DIST/COLUMBIA Rae eae gy, see eR Kee He He KF eK RD < > 





Input 


= 
LOSE ARR EH eae eS EDO Sette RAR IANA 


SS SSN SaaS 


Ra, OL Sane oe 
510 se 2 &@ € e ee eee <> 
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Output 


eek eR eR Ke ee EH oF < > 





Input 


756,518 ee ee ee Kee <Ts 





Output 


ADD COMPLETE 77/12/27 15:58:54 





The asterisks (*) under STATE-POP and under CAPITAL constitute the update formats. 
The characters (<< >) at the end of the output aid the terminal operator in placing the 
cursor in subsequent input; that is, the operator should place the cursor between the 


two special characters (< >) after overwriting the desired items. This ensures that the 
entire message is transmitted. 


The question marks (?) in the second output tell the operator that the value keyed in 
for STATE-POP is invalid (the period should be a comma). After the operator corrects 


the item in the third input, UNIQUE adds the record to the file and notifies the 
operator in the third output message. 
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Example 2: 


Input 


ADD COLORADO 





Output 


>STATE STATE-POP CAPITAL | 
COLORADO es. 2 ee eee cece Ree Re eee <> 





Input 


DENVER <> 





Output 


DENVER 
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1,986,008 DENVER 






ADD COMPLETE 77/12/27 16:62:33 


Example 2 demonstrates an ADD sequence in which the terminal operator attempts 
to add a state record without giving a value to STATE-POP. The exclamation points in 
the second output indicate that the STATE-POP item was defined as a MUST ADD | 
item in the data definition for this file. The operator must supply a value for STATE- & 
POP before this record can be added. 


NOTE: 


If a numeric item to be added begins with a decimal point, the terminal operator must 
key in the decimal point, even if the new value is zero. 


If the operator enters the OK command during an ADD sequence, UNIQUE adds the 
designated record with all the valid items. Any invalid items except those identified as 
MUST ADD in the data definition. The ADD command ts canceled if the MUST ADD items 
are not valid. (See example 3.) 

Example 3: 


Input 


ADD MISSOURI 
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Output. 


D>STATE STATE-POP CAPITAL 
MISSOURI Rta eee eer ese Oe eeecee ene ane & 
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& Input 


SS 


JEFFERSON CITY <p 





Output 


Seer 


Se sees sf 
2222227222272727? 





Input 


Output 


ADD COMPLETE 77/12/27 16:03:46 





This example demonstrates the use of the OK command with the display format ADD 
command. The OK command (input 3) causes UNIQUE to add the MISSOURI record, 
which supplies values to the valid items. in this case, the STATE-POP item contains 
the value 4,583,000, and the CAPITAL item contains the null value. 
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6.2.8.2. Hard Copy Format 
Basic Format: | 


ADD identifier item-name=value[;[item-name=]vatue]... 


General Format: 
ADD identifier[;]...[item-name=]value[[;]...,[item-name=]value]... 
NOTE: 
The general format is an expanded form of the basic format. 
where: 


identifier 


Is the record designation. (See the DISPLAY command, 6.2.3.) 


item-name 
Names an item. An item name can be any name, other than an identifier name, 
that appears as a column header in a DISPLAY command. The equal sign must 
be coded immediately after each item name. The item names need not be coded 
in the order of their appearance in the display record. 


Item names can be omitted, in which case they are inferred from the position of 
the value in the input message. The positions of values are determined from the 
last specified item name, forward in a consecutive manner. If no item names are 
specified, positional locations are assumed from the first item after the identifier. 
Any consecutive item that is not to be updated can be omitted by coding a 
semicolon (;) in its positional location. 


value 
Is the value to be stored in item-name. All values, except the last, must be 
followed immediately by a semicolon (;). 


In response to this command, UNIQUE displays the item names and values specified in the 
command, along with the identifier of the record. If the terminal operator is satisfied with 
the new record, he keys in OK, thus effecting the addition of this record to the file. If he 
decides not to add the record, he keys in the CANCEL command. 


In response to the hard copy format ADD command, UNIQUE also displays error notations 
when invalid item names or conditions are discovered. It displays invalid item names 
showing location in the input message, the invalid name, and the associated values. 
UNIQUE formats and displays all acceptable input for visual verification. The terminal 
operator can then decide to cancel the command or to correct the errors. 
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The operator makes corrections by entering a new input message with either the item 
name and value (for example, NAME-5=VALUE-5), or just the value (for examples, 
;,,VALUE-5) that is to be respecified. The operator does not enter the ADD command again 
when he is respecifying. UNIQUE responds by displaying all the original output, with the 
respecified values replacing the values in error. The terminal operator then keys in OK to 
effect the update, or CANCEL to cancel the entire ADD command. 


NOTE: 


The hard copy format may also be used with display devices. 


Example 1: 

Input ADD DIST/COLUMBIA STATE-POP=756.519 
STATE STATE-POP 

Output DIST/COLUMBIA ??,2272,22? 

Input STATE-POP=756,519 
STATE STATE-POP 

Output DIST/COLUMBIA 756,518 

Input OK 

Output | ADD COMPLETE 77/12/27 16:65:65 





This example illustrates the use of the basic hard copy format with only one value 
specified. The question marks in the first output message indicate that the value 
keyed in for STATE-POP is invalid (because it contains a decimal point). The corrected 
value is entered, and the OK command is issued to add the record to the file. 


Example 2: 
Input OPEN TOWNS 
ADD ALABAMA,CLARK,THURMONT POPULA=16,767 
TOWN MAYOR POPULA 
tput 
Outp ALABAMA,CLARK,THURMONT HI} !1!trrrerrs 16:767 
input MAYOR=BAKER, RICHARD 
TOWN MAYOR POPULA 
Output ALABAMA,CLARK, THURMONT BAKER, RICHARD 16,767 


Input OK 
Output ADD COMPLETE 77/12/27 16:06:13 





The exclamation points marks under the MAYOR item name indicate that a value for 
that item must be included to add a town record to the file. 
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6.2.9. CHANGE 


The CHANGE command initiates a series of inputs and UNIQUE responses which change a 
record in the file. Like the ADD command, the CHANGE command has two formats - the 
display format and the hard copy format. 


When using the IBM 3270 display station under UNIQUE, your command input or 
responses to UNIQUE messages must be in hard copy format rather than display format. 
The reason for this is the IBM 3270 display station transmits a whole screen of data to the 
UNIQUE program instead of a data field limited by a start-of-entry (A) symbol and the 
cursor. 


Upon successful completion of the CHANGE function, UNIQUE establishes a new rollback 
point for the current transaction. 


The CHANGE command places the terminal in an update state. While the terminal is in 
this state, no UNIQUE commands are accepted except OK or CANCEL. 


6.2.9.1. Display Format 
Format: 


CHANGE identifier-l[;identifier-2]... 


where: 


identifier-1l 
Is the record designation. (See DISPLAY command, 6.2.3, for further 
explanation.) 


identifier-2 
Designates another record in the file. 


In response to the CHANGE command, UNIQUE sends to the terminal the item names that 
serve as column headers, the old values, and the update formats of the items associated 
with the specified record. The terminal operator can depress the tab key to advance the 
cursor to the beginning of each update format. (Note that an extra character position is 
provided for the sign of numeric items.) The terminal operator overwrites the update 
formats with the associated new values and then transmits the modified screen. lf 
UNIQUE finds no errors, the modified record replaces the old record in the file and the 
terminal operator is notified. 


If errors are discovered, UNIQUE returns the item names, old values, update formats, and 
either valid new values or error notations to the terminal for further modification by the 
terminal operator. 


At any time during this sequence, the operator can enter the CANCEL command to cancel 
the CHANGE command instead of overwriting the update formats with values. The 
operator can instead key in the OK command to make changes to all valid items. Items for 
which invalid values have been specified remain unchanged in the file. 
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NOTE: 





lf a numeric item to be changed begins with a decimal point, the terminal oprator must 
key in the decimal point, even if the new value is zero. a 


Example: 


Input 


CHANGE ALABAMA, BREWSTER,LEWIS 





Output 


a gs ae ; bios 


TOWN MAYO POPULA 
ALABAMA,BREWSTER, LEWIS BROWN,HENRY 8,746 


see eRe &€ €E KE KH * * + @ ** & 
, ’ 





Input 





Output 


CHANGE COMPLETE 77/12/27 | 16:99:61 





The absence of asterisks under TOWN in the first output indicates that the operator 
cannot change that item. Items that cannot be changed contain blanks instead of 
asterisks in the update format line. 
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6.2.9.2. Hard Copy Format 
Basic Format: 


CHANGE identifier item-name=value[;[item-name=]value]... 


General Format: 


CHANGE identifier[;:]...[item-name=]value[[;]...,[item-name=]value]... 


NOTE: 
The general format is an expanded form of the simple format. 
where: 


identifier 


Is the record designator. (See DISPLAY command, 6.2.3.) 


item-name 
Names an item. An item name can be any name, other than an identifier name, 
that appears as a column header in a DISPLAY command. The equal sign must 
be coded immediately after each item name. The item names need not be coded 
in the order of their appearance in the displayed record. 


Item names can be omitted, in which case they are inferred from the position of 
the value in the input message. The positions of values are determined from the 
last specified item-name forward in a consecutive manner. If no item names are 
specified, positional locations are assumed from the first item after the identifier. 
Any consecutive item that is not to be updated is omitted by coding a semicolon 
(;) in its positional location. 


value 
Is the new value to replace the old value in item-name. All values, except the 
last, must be followed immediately by a semicolon (;). 


In response to this command, UNIQUE displays the item names, original values, and 
values specified in the command, along with the identifier of the record. If the terminal 
operator is satisfied with the new record, he must key in OK to change this record in the 
file. If he decides not to change the record, he keys in the CANCEL command. 


In response to the hard copy format CHANGE command, UNIQUE also displays error 
notations when invalid item names or conditions are discovered. UNIQUE displays invalid 
item names showing location in the input message, the invalid name, and the associated 
values. UNIQUE formats and displays all acceptable input for visual verification. The 
terminal operator can then decide to cancel the command or to correct the errors. 
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Corrections are made by entering a new input message with either the item-name and 
value (for example, NAME-5=VALUE-5), or just the value (for example, ;;;;VALUE-5) that is 
to be respecified. The operator does not key in the CHANGE command again when he is 
respecifying. UNIQUE responds by displaying all the original output, plus the respecified 
values displayed beneath the item names and old values for items previously in error. The 
terminal operator must then key in OK to effect the update, or CANCEL to cancel the 
entire CHANGE command. 


NOTE: 
The hard copy format also is used with display devices. 


Example: 


Input CHANGE ALABAMA, BREWSTER,MOREHEAD ;14,725 
TOWN POPULA 
Output ALABAMA, BREWSTER ,MOREHEAD 14,359 
14,725 
Input OK 
Output | CHANGE COMPLETE 77/12/27 16:89:57 





In the first input, the item POPULA is inferred from the position of the value, based 
on the preceding semicolon. An OK command requests UNIQUE to go ahead with the 
valid change. The resulting new record then changes only the POPULA item. 


6.2.10. LIST 


The LIST command selects certain records or parts of records for listing at the terminal 
based on the text of the command. It can also display the results of arithmetic expressions 
and statistical functions. 


LIST parameters are positional; tf used, they must be specified in the order shown in the 
format. 


Format: 


LIST [[display-content-spec][IF selection-criteria];]... 
[FOR a a as, 
FROM 
 [statistical-function [item-name-1l [,item-name-2]...]]... 
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where: © 


display-content-spec | 
Indicates the elements of the selected records that are to be displayed. The 
display content specification can be: 
=  record-name —- the name that represents the entire record; 
=» ALL - all items of the record (functionally equivalent to record-name) 
bs subrecord name - a name that represents a subset of items in a record 
= jtem-names -— identifying individual items in the selected record 
| F selectioeseriteria. 
Indicates which records are to be selected on the basis of conditional 


expressions. A simple conditional expression is a comparison between an item 
and another item or a literal value. The comparison operators are: 


EQ or = Equal to 

NE Not equal to 

GT or > Greater than a 
GE Greater than or equal to sd 
LT or< Less than 

LE Less than or equal to 


If the item is compared to a nonnumeric literal, the literal can have the same 
number of characters as the item or it can be shorter. If it is shorter, UNIQUE 
compares the characters in the literal with the same number of characters in the 
item, starting from the left. The remaining characters in the item are ignored. For 
example, the command LIST MAYOR=‘STAN’ would select all mayors’ names 
beginning with the letters STAN. 


A conditional expression can be negated by preceding it with the word NOT. 
Conditional expressions also can be combined by Boolean operators (AND,OR) 
into more complex conditional expressions. Within a conditional expression, NOT 
is first evaluated, then AND, finally OR. The order of evaluation is changed by the 
use of parentheses. 


FOR identifier-1 
Restricts the output of the LIST command to a subset of the file. The record 
specified by identifier-1 and all subordinate records to that record are then 
considered for listing. 
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eae identifier-2 
FROM 


Indicates the first record to be considered for listing. The FROM clause starts 
with the record specified by identifier-2 and lists all selected records, including 
the one specified by identifier-2. The AFTER clause lists all selected records after 
the record specified, not including the one specified by identifier-2. 


statistical-function [item-name-1l [,item-name-2]... ] 7 
Requests the calculation and display of the results of certain statistical functions. 
Statistical functions are performed at all levels. The specifications for statistical- 
function include: 


AVG 
Calculates and displays the average of the numeric items from the 
records selected. 


COUNT | 
Displays the number of occurrences of records that meet the selection 
criteria. No item name ts specified. 


MAX 
Finds and displays the maximum value of the numeric items from the 
records selected and the identifier of the particular record in which it is 
found. 


MIN 
Finds and displays the minimum value of the numeric items from the 
records selected and the identifier of the particular record in which it is 
found. 


TOTAL 
Accumulates and displays the value of the numeric items from the 
records selected. 


item-name | 
Names a numeric item. Item-name can be any name, other than an identifier 
name, that appears as a column header for this perote type, so long as its values 
are defined to be numeric. 


UNIQUE saves the text of the LIST command. This allows the terminal operator to reuse 
corresponding portions of the last LIST command to construct another LIST command. 


When the defined file contains several types of defined records, the user specifies the 
display-content-spec and/or IF selection-criteria (delimited by the semicolon) separately for 
each type of defined record. 
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LIST parameters are positional; if used, they must be specified in the order shown in the 
command format, and in the same order in which their corresponding defined records 
were defined. This then is the order in which the different types of defined records appear 
on the screen in response to the LIST command. UNIQUE uses the position of parameters, 
indicated by the semicolons, to determine the defined record to which the parameters 
apply. (See examples 2, 4, and the example for the DETAIL command, 6.2.12.) 


Example 1: 


Input 


OPEN STATES 


LIST STATE,CAPITAL IF STATE-POP < 508,698; 





Output 


CAPITAL 
JUNEAU 


CARSON CITY 
MONTPELIER 
CHEYENNE 





The OPEN command makes the STATES file accessible. The LIST command requests 
the STATE and CAPITAL item names and values to be listed for those records in 
which the value of the STATE-POP item is less than 500,000. Note that they required 
final semicolon (;). 


The END LIST status indication is displayed on the final screen of listed information. 
Another instance when END LIST occurs without data is when a defined file was 


accessed and the physical file used to create the defined record was closed via the 
ZZCLS command. 
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Example 2: 


Input 


OPEN TOWNS 


LIST STATE-RECORD; COUNTY-RECORD; TOWN-RECORD; 





Output 


* 
* 


* 


STATE 
-COUNTY 

-- TOWN 
ALABAMA 
-BREWSTER 
-- LEWIS 
--MOREHEAD 
--RIVERTON 
--WINSLOW 
-CARSON 

-- HOWELL 
--SCHUYLER 
-CLARK 
--ARDLEY 


GOVERNOR 
COUNTY SEAT 
MAYOR 


WRIGHT, GEORGE 


RIVERTOWN 
BROWN, HENRY 
WILSON, JAMES. 
JOHNSON, ALAN 
TURLEY, PAUL 
HOWELL 
SMITH, FRANKLIN 
LAWSON, PHILLIP 
HICKSVILLE 
LEE, JOHN 


>MORE 
CAPITAL 


POPULA 
MONTGOMERY 


9,986 
14,358 
38,623 

§,175 


7,968 
11,482 


3,618 


--BLACKSTONE MORLEY,DANIEL 


26,564 





This LIST command applies to the TOWNS file since that is the presently accessible 
file. The display-content-spec is a list of record names. The order of the record names 
is the order in which they are listed and must coincide with the order in which they 
are defined in the data definition. i 


This request is not satisfied in a single screen; that is, more state, county, and town 
records exist in the file. Therefore, a MORE LIST status indication is sent to the 
terminal operator. He requests the next screenful by keying in the MORE command. 
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Input 


LIST 


Output 


“STATE 

" + COUNTY 

"+ - TOWN 
ALABAMA 
-BREWSTER 
-- LEWIS 
--MOREHEAD 
--RIVERTON 
--WINSLOW 
-CARSON 
-- HOWELL 
--SCHUYLER 
-CLARK 
--ARDLEY 


GOVERNOR 
COUNTY SEAT 
MAYOR 
WRIGHT, GEORGE 
RIVERTON 
BROWN, HENRY 
WILSON, JAMES 
JOHNSON, ALAN 
TURLEY, PAUL 
HOWELL 
SMITH, FRANKLIN 
LAWSON, PHILLIP 
HICKSVILLE 
LEE, JOHN 


>MORE 
CAPITAL 


POPULA 
MONTGOMERY 


9,688 
14,3590 
38,623 

5,175 


7,960 
11,482 


3,618 


6-30 


--BLACKSTONE MORLEY, DANIEL 26,594 





Note that LIST with no further text requests the entire file to be listed. In this case 
the LIST command keyed in produces the same output as example 2. 


f 


Example 4: 


Input 


LIST ;COUNTY-RECORD; FOR OHIO TOTAL POPULA COUNT 
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} Output 


OHIO 

-COUNTY COUNTY-SEAT 

-ALBERMARLE HIGGINS 

-ALBERMARLE: TOWN=4 TOTAL POPULA= 198,759 
-CHARLES AVALON 

-CHARLES: TOWN=17 TOTAL POPULA= 263,858 
-DUQUESNE BRADFORD 

-DUQUESNE: TOWN=3 TOTAL POPULA= 25,643 
-GREENE ROBBINSVILLE 

-GREENE: TOWN=5 TOTAL POPULA= 37,262 


-LA SALLE | EVERETT 

-LA SALLE: TOWN=12 TOTAL POPULA= 184,595 

-MONROE LORETTA 

-MONROE: TOWN=2 1 TOTAL POPULA= 678,434 

OHIO COUNTY= 6 COUNT TOWN= 62 
POPULA= 1,192,543 








The display-content-spec for this LIST command requests the listing of only the 
county records from the TOWNS file. The first semicolon (;) indicates that no detail 
from the STATE record is desired. This semicolon is used to indicate omission; record 
names must appear in the order in which they have been described in the data 
definition. Also, the listing is restricted to those county records whose identifiers 
begin with OHIO (that is, those counties that are in the state of OHIO), as requested 
in the FOR clause. 


Total lines also are produced because the terminal operator requests the total of the 
item POPULA and the count of town records and county records. Total lines are 
indicated by the number sign (#). In addition to the totals of POPULA for each county, 
a grand total for the state is automatically calculated. Similarly, the number of town 
records for the entire state is calculated, along with the number of town records for 
each county and the number of counties in Ohio. 


6.2.11. MORE 


The MORE command requests the next screenful of information according to the previous 
LIST or DETAIL command. 


Format: 


weed biatcan 
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The DETAIL and LIST options indicate which of the previous commands (LIST or DETAIL) @ 
that UNIQUE is to continue processing to provide the next screen of information. If only 

MORE is keyed in, UNIQUE outputs a screen in response to the last LIST or DETAIL 
command entered by the terminal operator. 


Example: 


Input 


DMORE LIST 1 





Output 


>MORE 
“ STATE GOVERNOR CAPITAL 
* -COUNTY COUNTY SEAT 
* --TOWN MAYOR POPULA 
. ALABAMA WRIGHT, GEORGE MONTGOMERY & 
- DAWSON HILLSIDE 


--HILLSIDE BLACKBURN, JOHN 73,564 
-- JACKSONVILLE LINDEN, HERBERT 36,356 

. -FLETCHER CRESCENT CITY 

—.-CRESCENT CITY JARMAN, STANTON 51,426 
--HAPSBURG WILLIAMS , JAMES 8,958 





UNIQUE anticipates the request by the operator to send more LIST information by 
supplying the MORE LIST phrase as part of its output (example 3 of LIST, 6.2.10). 
Thus, the terminal operator need only press the transmit button on the display device 
to input the MORE command. The data that is found between the start-of-message 
character (>) and the cursor(7) is transmitted to UNIQUE. Thus, UNIQUE receives the 
message MORE LIST and supplies the next screenful of information. 
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6.2.12. DETAIL 


The DETAIL command interrupts the processing of the previous LIST command to request 
the processing of a higher priority list. This command is especially useful for nesting list 
requirements. 


Format: 


DETAIL [[display-content-spec]{IF selection-criteria];]... 


[FOR identifier-1] 
ae cas 
FROM 


[statistical-function [item-name-1 [,item-name-2]...]]... 


See LIST command, 6.2.10, for explanation of the parameters. 


The DETAIL command is identical to the LIST command, except that its text is retained 
separately from that of the LIST command and may be used repeatedly. This means that a 
different listing operation can be accomplished with a DETAIL command without 
destroying the content specification, selection criteria, or position within the file of the 
previous LIST command. 


Example: 


Input 


LIST ALL; ALL; 





Output 









>MORE LIST 17 









* STATE GOVERNOR CAPITAL 
"  -COUNTY COUNTY-SEAT 
ALABAMA WRIGHT ,GEORGE MONTGOMERY 
-BREWSTER RIVERTON 
-CARSON HOWELL 
-CLARK HICKSVILLE 
-DAWSON HILLSIDE 


-FLETCHER CRESCENT CITY 
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Input ® 


DETAIL ;; TOWN-RECORD; FOR ALABAMA,CLARK 





Output 


















ALABAMA, CLARK PEND DETAIL 7 


*  .-TOWN MAYOR POPULA 
--ARDLEY LEE, JOHN 3,610 
--BLACKSTONE MORLEY, DANIEL 26,564 
--HICKSVILLE GREEN,WILL!AM 32,454 
-- LONGTREE BLAKE, EDWARD 5,761 
--POQUGHTON. HOLLOWAY, STEPHEN 6,822 


--RIVERSIDE  . BROOKE, JAMES 15,666 





In this example, the terminal operator uses the DETAIL command to interrupt the @ 
listing of states and counties to obtain a more detailed listing of the towns in a 
particular county. The MORE command at this point requests the next screen from 

the LIST command, since the DETAIL command has completed its processing. 


6.2.13. SHOW 


The SHOW command provides the terminal operator with a capsule data description of the 
defined file that is being accessed. This includes item names and subrecord names and 
their attributes. The command also informs the user about the most recent LIST and 
DETAIL operations. In addition, the SHOW command lists any DISPLAY command or any 
update command (ADD display format, CHANGE display format, or DELETE) having 
outstanding, unprocessed identifiers awaiting the entry of a NEXT command. These 
commands are listed, each followed by its unprocessed identifiers in their order of entry. 


Format: 


SHOW 
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IS 90 A 


UNIQUE uses the following symbols to format the output display in response to the SHOW 
command: 


Symbol Meaning 

| An identifier 

A A value must be supplied for an ADD command. 

A new value can be supplied for a CHANGE command. 


| A value must be supplied for an ADD command, and a new value can be 
supplied for a CHANGE command. 


D A new value cannot be supplied for a CHANGE command. 
Example: 
Input 
SHOW 71 
Output 
> END SHOW 
TOWNS 
* STATE-RECORD STATE GOVERNOR CAPITAL 
PLT EEEDLTPEETEL * 2% * Fe Fe HK HR FH s * * eee eee HR eK KH eH 
“ COUNTY-RECORD COUNTY COUNTY-SEAT 
PERULPUTELIUEGE *eoeke «&© * * © & He HK Ke eR 
* TOWN-RECORD TOWN MAYOR POPULA 


PIPE ELPIPeredel *x* cs *& & ee * «se 2 & * hg et eet e 


LIST ALL; ALL; 
DETAIL :;TOWN-RECORD;: FOR ALABAMA, CLARK 


The SHOW command displays the password TOWNS for the presently accessible file 
and lists the records STATE, COUNTY, and TOWN with the items they contain, and 
appropriate update formats for those items. The I's indicate an identifier for STATE, 
COUNTY, or TOWN. The asterisks indicate that new values can be supplied for 
GOVERNOR, CAPITAL, COUNTY-SEAT, MAYOR, and POPULA on a CHANGE 
command. In addition, the SHOW command displays the most recent LIST and 
DETAIL commands and their current parameters. 
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7. Batch Processing of Transactions 


7.1. PURPOSE AND USES OF BATCH TRANSACTION PROCESSOR 


The batch processor is an optional component of IMS 90 that can be added to any single- 
thread or multithread configuration having adequate main storage and other resources. It 
is not available to the user of basic IMS 90. You include batch transaction processing by 
specifying the BATCH parameter in the NETWORK section of the configurator. The batch 
processor enables you to input transactions in card format, instead of through a display 
terminal; its output is directed to the printer or a printer file. Batched transactions can be 
processed online (that is, concurrently with routine production operations involving the 
normal terminal communications network) or offline, when no terminal network need be 
configured or active. 


You can submit transactions to the batch processor either from card images filed in disk 
source modules or from card images included as embedded data in the job control! stream 
at IMS 90 start-up. In neither case is it necessary to allocate a card reader to the IMS 90 
job. 


A primary use of the batch transaction processor is to display a file in print at the end of a 
day's production, as a data base administrator, for example, might need to do to review in 
detail the state of a file after massive update activity. It also is useful for obtaining a hard- 
copy listing of the data contained in a defined file or subfile - an activity that is not 
practical in normal operations from a display terminal. 


Another important use of the batch transaction processor is to test new UNIQUE-based file 
query and update dialogs, designed for routine use at production terminals, as well as to 
test new user-written action programs that your operators initiate as transactions during 
normal production. Printed output listed by the batch processor reproduces ail input and 
output messages, as well as unsolicited output, and thus provides you with a permanent, 
hard-copy record of each transaction. 


7.2. PROCESSING AND OUTPUT 


Batched transactions are processed as if they originate from one or more actual terminals; 
the batch processor responds to one or a number of pseudoterminals created by the IMS 
90 configurator and lists output on a print file that is assigned to each pseudoterminal. 
This output is a step-by-step record of each transaction initiated. 
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Immediately after each input message, the batch processor prints the output message 
issued by the action program - with the exception of immediate or delayed internal 
succession. All input messages and output messages generated from one batch input 
source module (that is, from one batch pseudoterminal) are listed in the same print file 
and are not mixed with messages from any other source module. 


For UNIQUE dialogs initiated as batch transactions, the batch transaction processor lists 
what is normally seen as output by the terminal operator, formatted as it would appear on 
the remote terminal. In this case, each input message is printed above the output message 
response and starts in column 1. The SOE (start of entry) character and the cursor are not 
represented. Terminal diagnostic and error messages are included in the output listing. 
There is no identification of any part of the output listing with a specific batch 
pseudoterminal. 


Figure 7-1 illustrates an output listing created by the batch transaction processor for a 
UNIQUE dialog that opens a defined file to list its contents. The input messages include an 
OPEN, a LIST, six MORE LIST commands, and a CLOSE. 


The output message that follows the **IMS READY** output message contains the name 
of the source input module, BATCHIN, and the name of the file, IN, on which it resides. 
These are specified in the PARAM IN statement that immediately precedes it. (Automatic 
status messages - INPUT IN PROCESS, INPUT IN QUEUE, and ROLLBACK IN PROCESS - 
are never sent to a batch pseudoterminal.) 


The first input message, OPEN CUSTOMER, initiates the UNIQUE transaction; its response 
is the OPEN COMPLETE output message normally returned to the originating terminal. The 
output message in response to the LIST command is the first screenful of data records 
from the defined file, CUSTOMR; the entire file is listed by the response to the fifth MORE 
LIST command, as indicated by the END LIST response above the seventh output message. 
The next MORE LIST command, therefore, produces the normal error return displayed 
next, and the CLOSE command is followed by the routine CLOSE COMPLETE output 
message. 


For readability of the output listing, the input messages shown in Figure 7-1 are punched 
beginning in column 10. This is feasible because all of them are UNIQUE commands, and 
UNIQUE allows this measure of free-form input. Normally, input messages begin in 
column 1. 


In normal nonbatch operations, when a user-written action program terminates in delayed 
internal succession, no message is sent to the terminal operator; what otherwise would be 
the output message is queued by IMS 90 as input to the succeeding action and not 
displayed. For immediate internal succession, no message is sent to the operator or 
queued. Instead, IMS 90 makes the input and output message areas in main storage 
available to the successor action program. In batch operations, the message is not listed 
by the batch processor as either an output or an input message. With immediate or 
delayed internal succession, the next message the batch transaction processor lists is the 
output message from the succeeding action. 
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IMS READY @e 


// PARAM INSBATCHIN/IN 
READING SOURCE MODULE BaTCHIN FROm FILE IN 


OPEN COMPLETE 78/04/07 
LIST 
* Cust=-10 NAME 
BALANCE*DUE DUF-IN@“VaLUE 
e AAODAD ANY BUM 
0,00 ne00 
¢ BRBTL BRANNON'S BA 
0.00 meO0 
e CAIFS CARRIAGE TAVERN 
0.00 neO00 
e CL3M0 CLOVER LEAF ~ 
0.00 neOdQ 
MORE LIST 
@ ® CUST“1D NAME 
BALANCE=DUE DUE*IN@VaALUE 
e CREHA CREST PUB 
0.00 ne OU 
e CURA CUMBERLAND C; UB 
0.00 ne00 
© DEINS DEW DROP INN 
76225 me0U 
© FAILA FARRAH*S DEN 
0.00 7200 
MORE LIST 
e CUST"10 NAME 
BALANCE=pUuE DUE=IN@VaLUE 
e HASFR HANOVER HOUSF 
0.00 200 
© JO2nC JOCKEYS JOINT 
0.290 «00 
e LA7HB LAST CHANCE SALOON 
0.00 7200 
e LOZER LOGAN LIQUORE 
0.00 neO00 
Figure 7—1. 





OPEN CUSTOMR 
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OR F17°19 


ADDRESS 
YTD=-VOLUME 
BOWERY 
0.00 
8& TUMBLE LAe 
0-00 
137 ELM ST 
0.00 
35 MEADOW DRe 
1,896e24 


ADDRESS 
YTD=VOLUME 
6&6 HIGHLAND AVE 
6.90 
BAY AVEe 
0.900 
13 NITEFALL ST 
76025 
16 LION ALLEY 
243219 


11! 


ADDRESS 
YTD=VOLUME 
6&5 FOUNTAIN RD 
0-00 
27Q WINNER CIRe 
02900 
72 HOPE BLVDe 
0.00 
21 BARREL ROADP 
9.00 


PORTSIDE, 


7-3 


MORE 
CITY=STATE 


NEW YORK sNeYe 
PEMBROKE, PAe 
POPULAR», NeJe 


PASTURE, PAe 


MORE 
CITY=<STATE 


CREST CITY. PA 
Nede 
LIGHTHOUSF, PA 


HILLSIDE, PA 


MORE 
CITY=STATE 


GRAFTON, NeJe 
STRAITAWAY, PA 
GOINGVILLFE.,. PA 


POTTSBURG, PA. 


Example of Output Listed by Batch Transaction Processor {Part 1 of 2) 


LIst 


ZIP 

190010 
16513 
08613 


1616] 


LIST 


ZIP 


1633} 


08131 


16217 


16314 


LIST 


7IP 

08124 
146519 
161)1 


16420 
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MORE LIST 
MORE LIST 
e CuSster1D NAME | ADDRESS CITY=STATFEF ZIP 
BALANCE-0UE OUE*IN@“VaLUE YTD-VOLUME 
e LO2SC LOST CLIPPER. 25 SAIL CIRCLE HARBOR», NeJe 08304 
0.00 nreO0 0-090 
e PEIPS PERRY*S PUB : 142 PLANK STe PERRYVILLE, PA 16212 
0.00 meO00 0-090 . 
e REIPA RED LANTERN © 15 BACK ALLEY LEGALTOWN, Ney 6412 
75.35 e000 75235 
e RIAcL RITTER*S ROOST 46 CHICKEN LAe BARNYARD, PAe 14013 
0.00 e000 0-90 
MORE LIST 
MORE LIST 
® CUST“1D) NAME ADDRESS CITY=STATE Z1P 
BALANCE-DUE OUE*IN@“VaLUE YTD-VOLUME . 
e ROICS ROYAL NIGHTC; UB 147 CASTLE STe BLUFBLOOD, PA, 16310 
89.60 1e00 R960 
e SHICA SHAMROCK PALACE 121 CLANCY AVE IRISHTOWN, PAs 16225 
0.00 me00 0-90 
e SUSMH SUPPER CLUB | S57 MAIN HWYe OVERTON, Nede os0l5 
0.600 neO0 0-00 | 
e TOIFR TOWNHOUSE CAFE 19 FRENCH RDe SPURNBURG, PA.» 16611 
0.00 neOQO 0-00 
MORE LIST 
END LIST 
® CusT*r1D0 NAME ADDRESS CITY=STATE ZIP 
BALANCE@QPUE ODUE@*IN@VaLUE YTDN=-VOLUME 
e TR2HS TRYTON TOWER. 238 HIGH STe TINKERTOWN, PA 164663 
25.83 ne00 75-83 
e WO9RL WOODEN NICKE) 93 BUFFALO LAe MINTBURG, PAe 16621 
0,00 me00 0-090 
eo YDIRA YOUR DEMISE 100 REST AVEe BOOTHILL, MDe 10640 
0.00 ne00 0-00 
e YYOYY HOT SHOT | JOLLY ROAD BILUE BELL ,PAe 19000 
0,00 %e00 0-00 
MORE LIST 
ILLEGAL MORE COMMAND ERROR LIST 
CLOSE CuSTOMR 
CLOSE COMPLETE 78/04/07 0f217332 
Je 
Figure 7—1. Example of Output Listed by Batch Transaction Processor (Part 2 of 2) 
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Unsolicited, output can be generated in any online batch-initiated transaction. This is the 
result of issuing the SEND function call in a user-written action program or including a 
SWITCH transaction in your input. Unsolicited output in offline mode is not supported. In 
the online batch mode, if its destination is one or more online active terminals, unsolicited 
output is routed as for any other unsolicited output. 


Unsolicited output destined for another batch pseudoterminal is not supported. Unsolicited 
output addressed to the originating pseudoterminal is listed on its own print file. An online 
terminal must not send unsolicited output to a batch pseudoterminal. 


Transaction types processed in batch mode, online or offline, include the following: 


= UNIQUE dialogs - Initiated by the OPEN command and comprising any of the UNIQUE 
command repertoire | 


= Other transactions - Initiated by a 5-character transaction code (typically, these 
activate user-written action programs) 


s Two of the standard terminal commands (ZZTMD and ZZNRM). The ZZHLD, ZZRDY, 
ZZCNC, and ZZRSD terminal commands have no useful role in a batch transaction 
environment 


w SWTCH transaction - For terminal-to-terminal communication. 


No batch input message should include any of the master terminal commands; these are 
not allowed because the batch pseudoterminals may not be master terminals. 


7.3. CONTROLLING BATCH TRANSACTION PROCESSING | 


Control of batch transaction processing begins with the specification of batch processing 
in the IMS 90 configuration. Certain modifications to the IMS 90 execution run stream 
also are needed. 


Batch transactions can be processed in offline or online modes. Control of offline 
processing is essentially a matter of the order in which source input is presented in the 
control stream (7.5); whereas the ZZBTH master terminal command gives the online user 
considerable flexibility in determining when batch processing is to begin and end, and in 
specifying which input is to be processed and in what order (7.6). 


7.3.1. Effect of IMS 90 Configuration Options 


When considering how to control batch processing, you should first review the description 
of the BATCH keyword parameter in the NETWORK section of your input to the IMS 90 
configurator. This is the parameter that adds the batch processing modules to your IMS 90 
system. 
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When you have specified that the batch processor is to be configured using this keyword, 
the IMS 90 configurator generates one or more batch pseudoterminals, depending on the 
specification of the BATCH keyword parameter. If BATCH=YES is specified, one 
pseudoterminal is generated and assigned the terminal id BTH1. When the BATCH=n 
specification is used, the configurator generates the number of pseudoterminals 
designated by n; the terminal ids are BTH1.,...,BTH4. 


In a single-thread IMS 90 system, you process only one batch input source module or 
embedded data set at a time; the specification BATCH=YES and BATCH=1 are equally 
valid. In a multithread IMS 90 configuration, on the other hand, although you still process 
only one embedded data set at a time, you can process simultaneously up to the maximum 
number (n} of batch input source modules. This means that, if you have specified 
BATCH=3 to the IMS 90 configurator, you can process up to three source modules at one 
time, or one embedded data set and up to two source modules. In online mode, which you 
control by issuing the ZZBTH master terminal command, the number of ZZBTH commands 
that can be active simultaneously is likewise limited by the maximum number specified by 
the BATCH configurator keyword parameter. (The ZZBTH command is described in 7.6.1.) 


7.3.2. IMS 90 Control Streams for Batch Processing 


You have four areas of concern in coding the IMS 90 execution run stream when you are 
running batch transactions: 


1. assigning source module input files; 
2. assigning printer files; 


3. inserting PARAM statements to control the batch processor (these must always follow 
any other PARAM statements present); and 


4. embedding sets of input source data in the control stream. 


7.3.2.1. Assigning Source Module Input Files 


Unless all batched transactions are to be represented by data sets embedded in the control 
stream, you must name and create one or more source modules, containing the card 
images of your input messages, and place these modules in a disk library file. Each input 
disk file contains several modules. In the control steam, you must assign these source 
module input files to the IMS 90 execution job, using OS/3 job control conventions. The 
LFD-names of these input files are used in the PARAM IN statements described in 7.3.2.3. 
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®@ 7.3.2.2. Assigning Print Files to Batch Pseudoterminals 


A print file must be assigned to each batch pseudoterminal that the IMS 90 configurator 
has been directed to generate by your specification of the BATCH configurator keyword 
parameter. The LFD-names expected by the batch processor for these print files are: 


terminal-id print file LFD-name 
BTH1 PRNTR1 
BTH2 PRNTR2 
BTH3 PRNTR3 
BTH4 PRNTR4 


Again, the assignment of these files follows OS/3 job control conventions. 


7.3.2.3. Invoking and Controlling Batch Processor (PARAM Statements) 


Batch processor parameter statements always follow any other PARAM statements in an 
IMS 90 execution run stream. If there are no other PARAM statements in a single-thread 
| IMS 90 run stream, batch processor parameter statements immediately follow the EXEC 
® Statement. In the run stream for a multithread IMS 90 load module, the PARAM BATCH 
statement immediately follows the PARAM START or PARAM RESTART statement, if there 
are no other PARAM statements to be placed there. Optional PARAM IN statements 
indicating source module input files to be processed (if any), immediately follow the 
PARAM BATCH or PARAM BA statement. 


PARAM BATCH format: 





// allel be Wo 


BATCH Jorrcine 
ONLINE 


where: 


BA 


Is the alternate, short form of the BATCH keyword parameter. 





Specifies that the configured batch processor is not to be invoked during this 
execution of IMS 90 and causes the main storage allotted to batch subroutines to 
be released for other uses by IMS 90. 


OFFLINE 


| Specifies that batched transactions are to be soenesed in offline mode; that is, 
& without an active terminal network. 
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ONLINE 
Specifies that batched transactions are to be processed in online mode. This 
mode requires a communications network, including at least the master terminal, 
to be configured and active. Batch processing is controlled by the ZZBTH master 
terminal command. 


If you have: created and filed batch input source modules, you insert into the control 
stream PARAM IN statements for those that are to be processed, following the PARAM 
BATCH statement. There may be any number of PARAM IN statements (or none), and the 
order in which they appear in the control stream is your option. If sets of batch input card 
images are embedded in the control stream, these may be interspersed freely among the 
PARAM IN statements in whatever order you want. 


PARAM IN format: 


// PARAM IN=module-name/file-name 


where: 


module-name 
Is a 1- to 8-character name of a source module containing card images of input 
messages to be processed by the batch transaction processor. This module 
resides in the disk file named by the file-name parameter. 


file-name 
Is the 1- to 8-character name of the disk file on which the source module 
resides. The file-name parameter must match the LFD-name specified in a job 
contro! statement assigning the file to the current execution of IMS 90. 


Is a separator between the module-name and file-name parameters and must be 
coded as shown. It cannot be preceded by a blank, nor be followed by a blank. 


7.3.2.4. Embedding Source Data in Control Stream 


At your option, you embed sets of card images of input messages in the batch processor 
control stream, following OS/3 job control conventions. These can be interspersed freely 
among the PARAM IN statements (Figure 7-2). However, for better performance in 
multithread batch processing, you should group all embedded data sets last, behind (after) 
all your PARAM IN statements. 


7.3.2.5. Sample Control Stream 


Figure 7-2 illustrates a control stream for executing a multithread IMS 90 system for 
online batch transaction processing. Note that the arbitrary LFD-name of the input source 
file (SRFILE), assigned in a DVC-LFD job control sequence, is repeated in the two PARAM 
IN statements later in the control steam; one PARAM IN statement calls for processing of 
transactions in a module of SRFILE named TEST. The other statement refers to a module 
in this file named PROD. This example assumes that BATCH=4 is specified in the 
NETWORK section input to the IMS 90 configurator (the number of printer files assigned 
to the job indicates this). 
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< > 


// JOB IMSBATCH, ,36EE8 

// DVC 58 // VOL 123456 // LBL NAMEREC // LFD NAMEREC 

// DVC 58 // VOL 123456 // LBL AUDFILE // LFD ae 

// OVC 58 // VOL 123456 // LBL CONDATA // LFD CONDATA 

// DVC 58 // VOL 123456 // LBL TCIDTF // LFD TCIDTF,,INIT 

// DVC 58 // VOL 123456 // LBL DQFILEL // LFD DOQFILE1,, INIT @ 
// DVC 58 // VOL 123456 // LBL DQFILE2 // LFD DQFILE2,, INIT 

// OVC 58 // VOL 123456 // LBL DQFILE3 // LFD DQFILE3,,1NIT 


lo 
// OVC 58 // VOL 123456 // LBL DQFILE4 // LFD SRFILE 
+@ 
// DVC 26 // LED PRNTRI 
// OVC 28 // LFD PRNTR2\ = 
// DVC 28 // LED PRNTR3 
// OVC 28 // LFD PRNTR4 
/&/ OPTION DUMP 
// EXEC ZQ#IMS,LOAD,1© 
// PARAM START Q) 


// PARAM BA=ONLINE 
// PARAM IN=TEST/SRFILE 


/$ 
aes . 
// PARAM IN=PROD/SRFILE 
/$ 
7 * 
/& 
// FUN 
NOTES: 
G) A single-thread IMS 90 system uses the AUDCONF file in lieu of these. 
(2) Not required for offline batch mode, which does not use a terminal network. 
GB) Assign user data files 
(4) Assign source module input files referenced in ZZBTH master terminal commands. 
6) Assign printer files; one for each batch pseudoterminal created by the configurator. Equal in number to the number 
specified in the BATCH configurator keyword. 
© The program name on the EXEC statement must match the LOADM parameter specification on the IMSCONF jproc 


©@Ooe 


at configuration. The default name for multithread IMS 90 is ZO#IMS; the default name for single-thread IMS 90 is 
ZS#IMS. 


For offline mode, code this as 7/7 PARAM BA=OFFLINE. 

Batch input cards 

Param !N statements, or embedded data sets, or both, are required for offine batch mode. Data sets may be freely 
interspersed among PARAM IN statements. These are optional in online batch mode and when present are 


processed through one or more ZZBTH*(,ALL) master terminal commands. If absent in online batch me: 3, the 
module-name, filename form of the ZZBTH command is used to specify all input source modules to be processed. 


Figure 7—2. Sample IMS 90 Execution Run Stream for Online Batch Processing in a Multithr. tem 
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7.4. PREPARING TRANSACTION INPUT FOR BATCH PROCESSOR 


Input for the batch processor is in the form of card images, either filed on disk or included as 
embedded data sets in the IMS 90 execution run stream. This capability provides the flexibility 
needed for batch testing as well as for standard batch production runs. Note that action 
programs using screen formatting services may not run in a batch (online or offline) 
environment. 


7.4.1. Input Message Coding 


Each input message is punched into a card, or as many as 18 cards; messages are 
grouped in the sequence in which the operator enters them at the terminal. The batch 
processor takes input message text from card image columns 1 through 71. (Individual 
messages longer than 71 characters are continued onto the next card by coding a 
nonblank character in column 72; coding on the continuation card begins in column 1.) Up 
to 17 continuation cards are allowed, giving a maximum length of 1346 bytes for any one 
message. Columns 73 through 80 are reserved for sequence numbers which are not 
required or processed. Both input message text and device independent control 
expressions (DICE) are in EBCDIC code. 


When coding UNIQUE dialogs for batch transaction processing, you use the hard copy 
format of the ADD and CHANGE commands to avoid the laborious preparation of DICE 
sequences necessary if you use the display format. 


When coding an input message for a user action program that does not allow free-form 
placement of data characters, you code data in specific card columns. The SWTCH 
transaction, on the other hand, must always be coded beginning in input card column 1 
because this is the position expected by the SWITCH action program. 


Figure /~3 illustrates a sample UNIQUE dialog transaction prepared as input for batch 
processing, comprising 10 input messages and followed by two SWITCH transactions for 
sending unsolicited output to active online terminals. These card images constitute an 
embedded data set for inclusion in the control stream. Notice that no delimiter is required 
to separate the UNIQUE dialog from the SWITCH transaction code that follows it (the 
CLOSE command serves this purpose) and that nothing is used to mark the beginning or 
end of the source module. Notice also the handling of continuation for the input message 
that contains more than 71 characters. 


OPEN CUSTOMR 

LIST 

MORE LIST 

MORE LIST 

MORE LIST 

MORE LIST 

DISPLAY LA7HB 

DETAIL CUST-ID IF NAME GT .LOGAN LIQUORS -AFTER .LAST CHANCE SAL* 
OON 

MORE DETAIL 

CLOSE 

SWITCH T1,T2 THIS IS A MESSAGE 

SWITCH 13,T@ THIS IS A MESSAGE ........ ide Spat a tice etd es 2h Re eo a eee 


Figure 7—3. Sample UNIQUE Dialog Transaction Prepared as Input to Batch Transaction Processor 
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@ 7.4.2. Handling DICE Characters 


The characters used in DICE sequences that certain user-written action programs employ 
to format output messages are written as hexadecimal symbol pairs (using EBCDIC 
characters) in input messages prepared as batched transactions. To eliminate the 
requirement that the hexadecimal codes be multipunched, the batch processor employs a 
shift character (the ~| character, multipunch 11-7-8) to designate that all EBCDIC 
characters following it are to be treated as hexadecimal digits (O-9,A-F) until another ‘| 
character is scanned. Each pair of hexadecimal digits is converted to a single byte before 
being passed to the batch processor. Two “1 symbols in succession are converted to a 
single “1. For example, the following EBCDIC sequence in an input message: 


1 10040000 71 YES 10571 71 


is transmitted to the processor as the following: 


tyolor4jorojorojers} crs} ey2}oys 7 41 | 


NOTE: 
The first four bytes are the DICE sequence for position control to new line on a CRT 
device. 

& When the batch processor encounters DICE control sequences or the ESC (escape) 


character (27,.) in an output message area, it strips them before printing the message. 
This corresponds to the online handling of DICE codes and hardware characters which are 
not displayed on the terminal. An OMA could look as follows: 


a foTokt [ors Joroleys [eta] crsyeta]ets [ote]+foJoy 4]oyojorolor7|ere]2t7[ors|ore 
nnn <n aan 


DICE Control Sequence Message Text Dice Control Sequence Msg. Text ESC HT Msg. 
| Text — 


The print lines of this message after batch processing sake as follows: 
First line: ABCDEF 
Second line: GHI 
Note the deletion of DICE control Sequences and the ESC character (27,5) and HT 


(horizontal tab, 0O5,.). 


7.5. CONTROLLING BATCH PROCESSING IN OFFLINE MODE 


Because IMS 90 executes without a communications network in offline batch mode, there 
is no possibility of controlling batch processing via the master terminal. Batch input source 
© 7 files are assigned with statements in the IMS 90 execution run stream. 
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The BATCH=OFFLINE parameter statement is followed by IN parameter cards and/or 
embedded data sets of input card images; data sets are freely interspersed. The order in 
which these appear in the streams is the order in which the batched transactions they 
represent are processed. Listed output is ordered by the batch processor automatically. 
You can only indirectly control its order by the sequence in which you submit your input 
and, in a multithread IMS 90 system, by the number of batch pseudoterminals you have 
generated via the BATCH configurator parameter. 


7.6. CONTROLLING BATCH PROCESSING IN ONLINE MODE 


IMS 90 requires an active communications network in the online batch processing mode. 
This requirement allows close control of batch processing from the master terminal, using 
the ZZBTH master terminal command to specify which source modules are to be processed 
and when. 


Batch processing that is conducted in online mode during normal production hours, when 
the regular operating terminals are busy, should be expected to downgrade performance. 
For this reason, online batch processing should be invoked during slow periods or prior to 
shutdown. An alternative is to invoke online batch mode during nonproductive time, 
perhaps configuring a special network consisting of the master terminal alone. 


Another factor affecting online batch performance is the number of batch modules being 
processed concurrently in a multithread IMS 90 system. The fewer the modules, the better 
the performance. The maximum number that can be processed concurrently is determined 
by the number specified with the BATCH configurator keyword, but the master terminal 
operator controls the number of modules that are submitted simultaneously to the batch 
processor (within the maximum limit) by his timing of the ZZBTH command. 


You assign batch input source files and printer files with job control statements in the IMS 
90 execution run stream. Following the PARAM START statement, you submit PARAM 
BATCH=ONLINE, optionally followed by PARAM IN statements and embedded data sets. 
No batch processing is performed until the first ZZBTH master terminal command is 
entered. Note that PARAM IN statements or embedded data are appropriate only if you use 
the ZZBTH *[,ALL] form of the ZZBTH master terminal command to control batch 
processing in online mode. The module-name,file-name form of the ZZBTH command does 
not take source input from the control stream. 


If you want to list the output printed by the batch processor before the termination of the 
IMS 90, you must instruct the system console operator to invoke the output writer by 
entering PR BU; if any print files are ready, printing will begin immediately. The purpose of 
entering the BU (burst mode) parameter is to avoid the normal printing of the IMS 90 job’s 
log file first. If only one printer is available, a spooling supervisor should be configured at 
system installation time. (This is necessary because a nonspooling supervisor prints the 
output as soon as it is generated by the batch processor.) Another consideration in a 
multithread system is that the system console operator cannot be reached via the IMS 90 
master terminal, although it is at this terminal that the operator controlling the batch 
processing online ascertains that processing has been completed for one or more modules 
and that the results are ready to be printed, if desired. | 
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The function, format, and parameters of the ZZBTH master terminal command and how to 
use it in controlling batch processing in online mode are described in 7.6.1 through 7.6.5. 


7.6.1. ZZBTH Master Terminal Command 


The ZZBTH terminal command is entered at the master terminal to initiate and control the 
batch transaction processor in online mode. Parameters are available to specify the source 
of input messages for each execution of the command, to control sequential progress 
through control stream input, and to terminate, suspend, or resume the batch transaction 
processing currently in progress. 


Format: 


ZZBTH{ module-name,file-name 
"[, ALL] | 
CANCEL 
PAUSE 
RESUME 


where: 


module-name 
Is a 1- to 8-character name of the source module that contains the card images 
of input messages to be processed by the batch transaction processor in online 
mode. When this module-name,file-name form of the ZZBTH command is used, 
the batch processor does not seek the input source module in the job control 
Stream, but locates it in the file named by the second parameter, file-name. 


file-name 
Is a 1- to 8-character name of the file on which the foregoing source module 
resides. The file-name parameter must match the LFD-name specified in a job 
control statement assigning the file to the current execution of IMS 90. 


Specifies that the next PARAM IN card or the next set of embedded data 
encountered in the IMS 90 command stream represents the source of input 
messages for this execution of the ZZBTH command. When this execution of the 
ZBTH command is the first for the current execution of IMS 90, the PARAM IN 
card or embedded data set used by the batch processor is the first one 
encountered in the run stream. If the current execution of the ZZBTH * command 
is not the first for the job, the card or embedded data set selected from the run 
stream is one occurring after the one used as the source of input messages 
processed by the immediately preceding ZZBTH * command. 
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ALL 

Specifies that the entire run stream will be processed, starting with the next 
source of input messages (represented by the * parameter specified with this 
execution of the ZZBTH * command). If the optional ALL parameter is omitted, 
processing of the run stream input stops when the next PARAM IN card or set of 
embedded data is processed. If a subsequent source module is represented in the 
run stream, therefore, you must enter another ZZBTH * [,ALL] command to 
process it. 


CANCEL 
Specifies that all batch transaction processing currently in progress is to 
terminate. Processing of each transaction ceases with the issue of the current 
output message to the print file, and the print file is closed. File modifications 
made since the beginning of the current transaction are not rolled back. The 
batch processor substitutes a ZZCNC terminal input command for the next 
expected input message. 


PAUSE 
Specifies that all batch transaction processing currently in progress is to be 
suspended. Processing of each transaction ceases with the issue of the current 
output message to the print file, but the print file is not closed. 


RESUME 
Specifies that all batch processing temporarily Suspended by the preceding 
ZZBTH PAUSE command is to resume from the suspended state. 


7.6.2. Initiating Online Batch Processing 


When the ZZBTH command is entered at the master terminal and the batch processor 
recognizes batch input, the message BATCH INITIATED is output to the master terminal, 
and processing begins. 


With single-thread IMS 90, only one ZZBTH command can be entered at a time; 
transaction processing in response to it must be completed before another ZZBTH 
command can be entered. In a multithread IMS 90 system, on the other hand, several 
ZZBTH commands can be processed simultaneously, up to the maximum number specified 
by the BATCH configurator keyword. 


If the master terminal operator attempts to enter a ZZBTH command in excess of the 
maximum number of batch modules that can be processed concurrently (or a single-thread 
operator enters a second command before the processing of the current command is 
done), IMS 90 responds with the following diagnostic message: 


TOO MANY ZZBTH COMMANDS ENTERED - COMMAND IGNORED 
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7.6.3. Tracking Progress of Batch Processing 


To determine when a batch run is complete, or to keep track of the processing of batch 
modules, the master terminal operator at any time can enter the ZZTCT master terminal 
command to access the terminal control table generated for any batch pseudoterminal, 
and specify the batch terminal id desired (BTH1,...,BTH4). The ZZTCT command provides 
the master terminal with a report of the activity outstanding at the specified terminal. (See 
5.2.2.4.) | 


7.6.4. Resuming Batch Processing Once Terminated 


Issuing the ZZBTH CANCEL command terminates only the ongoing batch processing; the 
transaction processing that has been accomplished is listed. There is nothing to prevent 
reprocessing the same modules or to prevent batch processing from being performed on 
other source modules. You can continue by issuing the appropriate ZZBTH command after 
having received the response to the ZZBTH CANCEL command in effect. The response to 
the ZZBTH CANCEL command is the message: 


BATCH PROCESSING CANCELLED 


The effect of issuing a ZZBTH *[,ALL] command after you have issued a ZZBTH CANCEL 
command is to read the control stream at the next data set present. If you issue the ZZBTH 
module-name, file-name form of the command, the specified module is processed from its 
beginning, not from where processing ceased if this was the module being processed 
when you issued ZZBTH CANCEL. 


7.6.5. Repetitive Use of Batch Mode 


There is no feature in the batch transaction processor that checks whether your files have 
been processed by the same input - in fact, batch mode facilitates reprocessing with 
repetitive use of the same input. This enables you to use the same program at the end of 
each day to list the state of your files and to review the day’s activity. 


7.7. CONTINUOUS OUTPUT CONSIDERATIONS 


Output delivery notification to a batch pseudoterminal is always generated as successful 
by the batch transaction processor. A program using output-for-input queueing can be 
testing in batch mode, but it is not reasonable to perform continuous output by this means 
in a batch production run. 


7.8. BATCH PROCESSOR DIAGNOSTIC MESSAGES 


In addition to the diagnostic and error messages normally output by IMS 90 to the 
operator at a production terminal (which the batch processor includes in the output listing 
for each batch pseudoterminal), the batch processor generates a set of its own messages. 
These it sends to the master terminal or includes in the output listing for the batch 
pseudoterminal, aS appropriate. Table 7-1 lists the texts of these messages, describes 
their causes, and indicates the corrective action that can be taken. 
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7.9. RECOVERY CONSIDERATIONS 


When recovery is invoked for batch processing, either cold or warm restart, the user 
enters a DLMSG input transaction via cards to the batch processor. One card is supplied 
for each batch terminal. For single-thread IMS 90, only one card is required. Using the 
printed output from this transaction (DLMSG), the user can decide what portion of his 
input batch module was processed before the system aborted. From this information the 
user can reconstruct his batch input card deck or use the librarian to edit a source library 
input message module. 


An example of a warm restart batch input for a single-thread batch system is: 


/$ 
OLMSG BTH1 
7% 


For warm restart, the before images for the files are restored at the start of the last 
transaction completed. 


Table 7—1. Batch Transaction Processor (BTP} Diagnostic Messages (Part 1 of 2) 


BATCH INPUT MODULE BTP attempts to access a non-existent input Check that module name is correct and that input 
READ ERROR module; or an t/O error has occurred; or the messages are indeed contained. Otherwise, action 
module contains no input messages. as for hardware error. 


INVALID BATCH The control stream contains an incorrect Correct the PARAM card. Refer to 7.3.2.3. 
PARAM CARD PARAM card. 


PRINTER FILE ERROR This message is sent to the master terminal Check that the file exists and that the LFD-name 
when a printer file cannot be opened or an is correct. Otherwise, action as for hardware error, 
unrecoverable hardware error occurs. 


READING SOURCE This message is printed upon successfully 
MODULE module-name opening the source input module file. 
FROM FILE 

file-name 


SOURCE MODULE This message is printed if the batch input Ensure that the source module exists in the file. 
module-name iN module is not in the library file. 

FILE file-name 

NOT FOUND 


READ ERROR ON An 1/0 error occurs while the BTP is As for hardware error 
MODULE module-name. reading the batch input module. 
FILE file-name _ 


TOO MANY CONTINUATION The BTP has encountered more than 17 Restrict each input message to the maximum number 
CARDS continuation cards. of cards: 18. Refer to 7.4.1. 


HEX CHARACTER ERROR The BTP prints this message to the right Revise coding between shift characters to 
of the input card image when an EBCDIC represent hexadecimal codes; see 7.4.2. 
character other than O—9 or A—F is coded 
between two input shift characters. 


HEX CHARACTER PAIRS The BTP prints this message to the right Revise coding between — 7 shift characters to 
INCOMPLETE of the input card image when the EBCDIC represent hexadecimal pairs; see 7.4.2. 
characters coded between two —7 shift 
characters are within the set O—9 or 
A-—F but are odd in number. 
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Table 7—1. 


BATCH NOT CONFIGURED — 
COMMAND IGNORED 


BATCH=NO SPECIFIED IN 
PARAM CARD —COMMAND 
IGNORED 


INVALID ZZBTH PARAMETERS 
~ COMMAND IGNORED 


TOO MANY ZZBTH COMMANDS 
ENTERED —- COMMAND 
IGNORED 


BATCH PROCESSING 
CANCELLED 


ALREADY READING BATCH 
CONTROL STREAM DATA 
SET —~ COMMAND IGNORED 


BATCH RESUMED 


BATCH INITIATED 


ZZBTH PARAMETER 
PROCESSING ERROR 


BATCH PROCESSOR NOT 
IN PAUSE — COMMAND 
IGNORED 


BATCH PROCESSOR NOT 
RUNNING — COMMAND 
IGNORED 


BATCH PROCESSOR IN 
PAUSE STATE 
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Output to master terminal in response to a 
ZZBTH command entered when BATCH=NO 
has been specified or the BATCH keyword 

is omitted from the NETWORK section 

of input to IMS 90 configurator. 


Output to master terminal in response to a 
ZZBTH command entered when batch 
processing has been specified to the IMS 90 
configurator but the PARAM BA statement 
has been omitted from the 1MS 90 run 
stream or PARAM BA=NO is specified. 


Output to master terminal in response to a 
ZZBTH command entered with incorrect 
parameters (syntax error}. 


Output to master terminal in response to a 
ZZBTH command entered in excess of the 
number which may be processed at one time 
is this configuration. In a single-thread 

IMS 90 system, only one ZZBTH command 
may be active at one time; entry of a 

second must be deferreduuntil conptetion 

of processing for the current command. 

In a muitithread system, the number of 
commands that may be processed simultaneously 
is linited by the maximum number specified 
withtthe BATCH configurator keyword. 


Normal response to successful ZZBTH 
CANCEL command; only the batch 
processing currently in progress 
terminates. 


Output to master terminal in response to a 
ZZBTH command entered before the processing 
of a data set in the control stream has been 
completed by the current ZZBTH command. 
Only one data set may be processed at a time; 
while one is being processed, no further 
PARAM IN statements may be processed. 


Normai response to successful ZZBTH RESUME 
command. 


Normal response to successful start of batch 
processing with the ZZBTH command. 


Output to master terminal in response to a 
ZZBTH command when an input module is 
missing, the end of control stream input is 
accessed, and so forth. 


Output to master terminat in response to a 
ZZBTH RESUME command entered when 
the BTP is not in a pause state. 


Output to master terminal in response to a 
ZZBTH PAUSE or ZZBTH CANCEL 
command when the BTP is not running or has 
completed processing. 


Normal response to a successful entry of the 
ZZBTH PAUSE command. 





Batch Transaction Processor (BTP) Diagnostic Messages (Part 2 of 2) 


If batch processing of transactions is intended, 
specify the BATCH keyword to the IMS 90 
configurator according to 7.3.1.1. 


Specify the intended PARAM BA statement 
in the IMS 90 run stream according to 
7.3.2.3. 


Reenter ZZBTH command with parameters 
conforming to those documented in 7.6.1. 


Defer reentry of the ZZBTH command until 
response to the ZZTCT command indicates 
that processing is again possible (7.6.3). 


None required. Batch processing may be 
reinitiated during this execution of IMS 90 
by entering an appropriate ZZBTH command 
(7.6.4). 


Defer reentry of the ZZBTH command until 
response to a ZZTCT command indicates 
that the current processing of a control 
stream data set is complete (7.6.3). 


None required. 


None required. 


Check for correct parameter information 
and reissue command. 


Do not reenter ZZBTH RESUME command until 
BTP is in a pause state: that is, until after 

receipt of normal response to ZZBTH PAUSE 
command. 


None required. 


None required. The only valid commands following 
the ZZBTH PAUSE commands are the ZZBTH RESUME 
or the ZZBTH CANCEL command. 
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Appendix A. Statement Conventions 


Throughout this document, certain conventions are observed for formats for user-Supplied 
Statements and commands. General rules with examples pertaining to these conventions 
follow. 


Capital letters and punctuation marks (except braces, brackets, and ellipses) must be 
coded exactly as shown. For example: 


CALL ‘GET’ USING file-name record-area record-number. 


is coded: 


CALL ‘GET’ USING CUSTFIL CUS-REC REC-KEY. 


Lowercase words that are not underlined represent information to be Supplied by the 
user. For example: 


ZZTCT terminal-id 


is entered on the terminal as: 


ZZTCT TRM1 


Information within braces }{ represents necessary entries, one of which must be 
chosen. 


For example: 


ae tee pcre eehena record-area, record-number ) 
(Z7G#CALL) (GETUP 


is coded: 


ZG#CALL GET,(STATE,RECORD, SNKEY) 
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2 Information within brackets [ ], including commas and semicolons, represents optional 
entries that are included or omitted, depending on program requirements. Braces 
within brackets indicate that one of the entries must be chosen if that operand is 
included. For example: 


ted 


is coded: 





JUS=L 


= Default parameter specifications are indicated by shading. For example, if no TYP 
parameter is specified as input to the edit table generator, the M is supplied, meaning 
alphanumeric type data is expected for the designated file. 


TYP=( A 


07 =z ew 


= An ellipsis (...) indicates the presence of a variable number of entries. For example: 


SWICHA terminal-id-n,... ;AAmessage-text 


is entered at the terminal as: 


SWITCH TRM1,TRM2,7TRM4,TRMG6; THIS IS THE UPDATE FILE: 


= A delta (A) indicates the presence of a space as shown in the example. 


Statement conventions and coding rules specific to individual functions are described 
where applicable throughout this document. 
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Appendix B. UNIQUE re 
Elements 


The standard lexicon for UNIQUE is automatically defined at configuration time. This 
appendix lists the elements of this language and how they are used by UNIQUE. 


OPEN 


CLOSE 


DISPLAY 


DELETE 


OK 


CANCEL 


ADD 


CHANGE 


NEXT 


LIST 


MORE 


DETAIL 


SHOW 


Begins a dialog 

Terminates a dialog 

Displays a record in a file 

Deletes a record in a file 

Finalizes update operation 

Cancels current update operation 

Inserts a record into a file 

Changes a record in a file 

Processes the next record, as mentioned in preceding command 
Lists records from a file 

Continues processing previous LIST or DETAIL command output 


Performs secondary listing operation 


Displays information about current dialog 
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Semicolon. Used to delimit identifiers and LIST requests 
Single quote or apostrophe. Used to indicate special character in identifiers 


Ditto character. Used to copy parts of previous commands 


Comma. Used to separate segments of identifiers and also used in the editing of numbers 


Set symbol. Used to set data values, in update commands (hard copy format) 
Decimal point. Used to indicate decimal! places 
Parentheses. Used in arithmetic expressions in LIST command 


Dollar sign. Used to designate dollar values 





Credit symbol. Used to indicate a negative money amount 


Logical Operators* 






Intersection operator 


Union operator 






Negation operator 






Equals operator 







Not equals operator 






Greater-than operator 






Greater-than-or-equal-to operator 


Less-than operator 






Less-than-or-equal-to operator 


Statistical Functions* 


Total operation 


Count operation 


Maximum operation 
Minimum operation 


Average operation 





*Used in LIST command 
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END 


NO 


PASSWORD 


INVALID 


ILLEGAL 


COMMAND 


MESSAGE 


RECORD 


TOO BIG 


IDENT. 


EOM 


DATATYPE 


I/O 


ERROR 


BAD 


DATA 


EXISTS 
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LIST Keywords 


Restricts output from LIST command 
Specifies records to be listed 
Specifies records to be listed 


Initiates selection criteria in LIST command 


Specifies records to be listed 


Status Indications 


COMPLETE 





Reports successful completion of a request 

Indicates the end of the LIST or DETAIL output 

Used in error messages (e.g., NO RECORD) 

Used in error messages in response to OPEN command 

Used in error messages (e.g., INVALID COMMAND) 

Used in error messages (e.g., ILLEGAL IDENT.) 

Used in error messages 

Used in error messages 

Used in error messages 

Used in error messages (e.g., RECORD TOO BIG) 

Used in error messages to convey information concerning identifiers 
Used in error messages to indicate the end of some input was unexpected (e.g., INVALID EOM) 
Used in error messages 

Used tn error messages (e.g., |1/O ERROR) 

Used in error messages 

Used in error messages 


Used in error messages to indicate an inconsistency between the value of an item and its description 
(e.g., BAD DATA) 


Used in error messages 
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Appendix C. Sample IMS 90 Application 


C.1. PREPARING AN RPG II APPLICATION 

This appendix is the step-by-step procedure for preparing an IMS 90 application using an 
RPG Il action program. The example action program (LSTLIM) accesses an ISAM file 
(STOCKS) and is activated by entering the transaction code STK at the terminal. 


The processing steps used to prepare the system for online RPG Il action program 
execution are as follows: 


1. ICAM network generation 

2. IMS 90 configuration 

3. File space allocation 

4. User logical file creation 

5. RPG Il action program compilation 

6. RPG Il action program linkage 

7. IMS 90 execution 

ICAM network generation must precede IMS 90 configuration. Action program compilation 
must precede linkage. Ail steps must be completed before IMS 90 execution, but 


otherwise, except as noted, may be done in any order. 

In this sample application, steps 3 and 4 are assumed complete; i.e., the disk space has 
already been allocated and the user logical file has been created. 

C.2. ICAM NETWORK GENERATION 


The first step is to generate the ICAM network for the action program, LSTLIM. Figure C-1 
shows the ICAM specifications for a resident transaction control interface (TCI) network. 
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1 10 16 


COMMCT 
TCll CCA TYPE=(TCI), PASSWORD=RPGIMS98, FEATURES=( TRACEMAX ) 

BUFFERS 18,128,1,ARP=35 
LNE1 LINE DEVICE=(UNISCOPE) , TYPE=(2408,SYNC,SWCH) , |ID=68 
TRM1 TERM ADDR=(28,51),FEATURES=(U269) , LOW=DQFILE1,MED1UM=MAIN,HIGH=MAIN 
TRM2 TERM ADDR=( 28,52), FEATURES=(U200), LOW=DQFILE1,MED!1UM=MAIN,HIGH=MAIN 
TRM3 TERM ADDR=(29,53),FEATURES=(U268), LOW=DQFILE1,MEDI UM=MAIN,HIGH=MAIN 


TRM4 TERM ADDR=(29,54),F EATURES=(U208) , LOW=DQFILE1,MEDI UM=MAIN,HIGH=MAIN 
P#H1 PRCS LOW=DQFILE1 
DQFILE1 DISCFILE FILEDIV=8 
TCIDTF DISCFILE MSGSIZE=2648 
ENDCCA 
MCP MC PNAME=C5 
CACH=(08,TC11,91) 





Figure C—?. ICAM Network Generation for RPG Mf Action Program, LSTLIM 


The ICAM network name (CCA label) is TCI1. This name must agree with the CCA name 
specified in the NETWORK section of the IMS 90 configuration (Figure C-2). In addition, 
the password RPGIMS90 must also agree with the password indicated in the NETWORK 
section of the IMS 90 configuration. 


The ICAM network (Figure C-1) describes one line with four UNISCOPE 200 terminals, 
each having three queues. The output queueing file is DOFILE1, and TCIDTF is the input 
buffer file. The name of the ICAM symbiont (MCPNAME) is C5, and the communications 
adapter port number of 08 is associated with this network in the CACH parameter. 


The system console operator places the card deck shown in Figure C-2 in the card reader 
and types in the following commands one at a time: 


RU SGS$PARAM 
RU SGS$COMMK 


After the SGSPARAM module is executed, the operator types in the second command to 
execute the SGSCOMMK module. This produces the ICAM symbiont and places it in the 
SYSLOD library. | 


C.3. IMS 90 CONFIGURATION 


The second step is IMS 90 configuration. Figure C-2 shows the IMS 90 configuration used 
for the LSTLIM action program. 
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@ // JOB IMSCONF, ,14880,14900 
// \MSCONF ZCNF=MT ,CCA=TC1I1,LOADM=1S1,INIT=(1) 
/& 
// FIN 
NETWORK CONFID=4 NAME=TCI1 PASSWORD=RPGIMS90 
GENERAL 
OPTIONS UNSOL=YES 
FILE STOCKS FILETYPE=ISAM 
BLKS!IZE=87 
RECSIZE=88 
IOROUT=ADDRTR 
KEYLEN=3 
KEYLOC=9 
|OREG=(8) 


KEYARG=STOCKS 
|IOAREAI=STOCKS 
TYPEFLE=RANSEQ 
TERMINAL TRMi MASTER=YES 
TERMINAL TRM2 
TERMINAL TRM3 
TERMINAL TRM4 , 
ACTION LSTLIM EDIT=# FILES=STOCKS INSIZE=27 OUTSIZE=968 
TRANSACT STK ACTION=LSTLIM 
PROGRAM LSTLIM ERET=YES 
// FIN 


Figure C—2. IMS 90 Configuration for RPG Il Action Program, LSTLIM 





The IMSCONF jproc calls five subordinate procedures that generate the control streams 
necessary to perform the IMS 90 configuration. The IMSCONF jproc specifies a 
multithread IMS 90 with a CCA named TClI1, an online IMS 90 load module named |S1, 
and file space initialized for NAMEREC, AUDFILE, and CONDATA IMS 90 files (INT=(I)). 


The NETWORK section of this configuration identifies the IMS 90 system records for the 
NAMEREC file, and names the CCA network and password in agreement with the ICAM 
generation specifications (TCI1 and RPGIMS90). 


The GENERAL section is optional. 


The OPTIONS section specifies unsolicited output, i.e., the SEND function and SWTCH 
command can be used. RPG Il uses the SEND function in the action program, LSTLIM, 
since multiple screens may be transmitted. 


The FILE section describes the user logical file used by the RPG II action program, LSTLIM. 
The user logical file is STOCKS. This name must agree with the LFD card on the device 
assignment for the user logical file (see Figure C-9). 


The TERMINAL section names four terminals with TRM1 as the master terminal. These 
names must agree with the terminal names on the ICAM generation (Figure C-1). 
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The action section names the RPG Il action program. This name must agree with the 
linked load module name (Figure C-3). If you anticipate the transmission of multiple blanks 
in a screen of data, you should use the EDIT=c parameter in the ACTION section where c 
indicates some infrequently used special character. Otherwise, multiple blanks are 
removed by the IMS 90 editing process. Do not use EDIT=NONE. RPG II cannot process 
the incoming DICE codes. The user logical file, STOCKS, is to be referenced and used by 
the LSTLIM action program. The INSIZE parameter must be used for all RPG,II action 
programs and the value must be equal to the record size specified on the file description 
specifications form for the IMA. 


The TRANSACT section specifies the transaction code of STK, which must agree with the 
transaction code keyed in by the terminal operator at RPG Il action program execution 
time. 


Finally, the PROGRAM section names the action program and specifies that control is 
returned to LSTLIM if an error occurs. | 


C.4. COMPILING AND LINKING THE RPG Ii ACTION PROGRAM 


To compile and link the RPG II action program, use the simple RPG and LINK jprocs shown 
in Figure C-3. 


JOB RPGACT 
RPG 


(action program) 


LINK LSTLIM, OUT=(RES,$Y$LOD) 


FIN 





Figure C—3. Compile and Link for RPG Il Action Program, LSTLIM 


Note that in linking the RPG II action program object module, the name of the load library 
where the action program load module is stored (SYSLOD) must agree with the library 
name (SYSLOD by default) on the LBL parameter of the IMSCONF jproc. 


Figure C-4 through C-8 show the specifications forms required to code action program 
LSTLIM, which accesses the STOCKS file for records within the lower and upper limits 
keyed in by the terminal operator. A line-by-line description also is provided. 








RPG It 
UINIVAC CONTROL CARD AND FILE DESCRIPTION SPECIFICATIONS 


DATE = eee, PAGE 2. OF ase PAGES 





PROGRAM _ CU PROGRAMMER 


CONTROL CARD SPECIFICATIONS 


FORMS ALIGNMENT t(NDICATOR INITIALIZATION 
INVERTED ALTERNATE SUBROUTINE 


PRINT COLLATING SIGN HANDLING FILE TRANSLATION 
SEQUENCE 


ERROR ANALYSIS 
OuMP GENERATE 


DEBUG CODE PROGRAM 


NOT USED 
IDENTIFICATION 


OPERATOR 
CONTROL 


NOT eaters 
10 16 


NOT USED 
NOT USED 


x 
z 
< 
a 
a] 
x 
Oo 
my 
*) 





FILE DESCRIPTION SPECIFICATIONS 


FILE ADDITION/UNORDERED LOAD 


CYLINOER OVERFLOW 
SPACE PERCENTAGE (X10) 





FILE PROCESSING MODE 


KEY OR RECORD 
ADDRESS FIELO LENGTH 





FILE TYPE 
FILE DESIGNATION 







EXTENSION OR 
LINE COUNTER 
CODE 










NUMBER 
OF BYTES 





NUMBER OF EXTENTS 
TAPE REWIND OPTION 
FILE CONDITIONERS 






SEQUENCE RECORD ADORESS TYPE 
FILE FORMAT FILE ORGANIZATION 


NAME OF 
NOT LABEL EXIT 
USED OR NAME OF 


IN MAIN 
STORAGE 
TO BE RESERVED 

























- OVERFLOW 
ra fod Eo INDICATOR DEVICE USER DEVICE FOR ISAM 
¥15]9 RECORD ROUTINE INDEX PROGRAM 
clole LENGTH KEY FIELD IDENTIFICATION 
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Figure C—4. LSTLIM Control Card and File Description Specifications Forms 
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RPG Il 
SPERRY<>UNIVAC FILE EXTENSION AND LINE COUNTER SPECIFICATIONS 


PROGRAM ow PROGRAMMER WU DATE LNUCéPAMGE OF PAGES 








FILE EXTENSION SPECIFICATIONS 





RECORD SEQUENCE k 
OF CHAINING FILE s|y rm 
ak $}2 
- © 
- CHAINING FIELO NUMBER ABE Sle ly 
TO TABLE OR OF ENTRIES EIQ] : a rd SaiaeNire PROGRAM 
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FILE NAME oia|o 318 
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a « 
45 [46 5556 157/58 


Figure C—5. LSTLIM File Extension Specifications Form 


| RPG I 
SPERRY<>UNIVAC INPUT FORMAT SPECIFICATIONS 


PROGRAM oO PROGRAMMER DATE LC RPAGE OF PAGES 
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Figure C—6. LSTLIM Input Format Specifications Form 


SNOILVOMddV 06 SII 


L ‘A8Y PLO8-d/N 


€/SO IVAINN AdYAdS 


9-9 





UP-8614 Rev. 1 SPERRY UNIVAC OS/3 C-7 








IMS 90 APPLICATIONS 
Figure C-4: 
Line Explanation 
1 The program is an action program named LSTLIM. 
2 The primary input file is INPUT and is the IMS 90 IMA consisting of one record 
2/7 bytes long. 
3 STOCKS is an indexed disk logical file processed by limits using the SETLL 


operation (see Figure C-7, Line 12). 


4 Output will go to the IMS 90 OMA, 904 bytes long, including ten 80-byte records 
and 104 bytes for headers and control characters. 


Figure C-5: 
Line Explanation 
5 ARY is defined as an array having 10 entries of 80 characters each. 
Figure C-6: 
© Line Explanation 
6-8 The input record format is defined. The first 16 bytes contain the IMA header. 


Bytes 17 through 20 contain the 3-character transaction code (STK) followed by 
a blank. This transaction code must also be specified in the TRANSACT section of 
the IMS 90 configuration (Figure C-2). The header information and transaction 
code are not referenced in this action program. Bytes 21, 22, and 23 contain the 
starting stock symbol (lower limit of the search). Bytes 25, 26, and 27 contain the 
ending stock symbol (upper limit of the search). 


9-11 The logical file disk records are each 80 bytes long with a key (the stock symbol) 
in the first three bytes. 
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Figure C—7. LSTLIM Calculation Specifications Form 
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Figure C—8. LSTLIM Output Format Specifications Form 
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Figure C-7: 

Line Explanation 

12 The starting point is set to the lower limit entered by the terminal operator. 

13 The array index is set to 1. 

16 A record is read from the disk file. If end-of-file has been reached, indicator 20 is 
set on. 

17 If the key is beyond the upper limit entered by the terminal operator, indicator 20 
iS set on. 

18 A record is moved to the array. 

19 The array index is incremented. 

20 lf the array is full, indicator 30 is set on. 

21, 22 If the array is full, it is displayed using the EXCPT operation and the index is 
reset to 1. 

23 lf there are more records to process, the program returns to LOOP. 

25, 26 If there are no more records to process, a test is made to determine whether the 
array Is partially full. If it contains any records, the last screen is displayed. 

Figure C-8: 

Line Explanation 

27, 28 The output record is defined. Exception output is used where the array is full or 
when a last partial screen is reached. 

29 The first 16 positions contain the OMA header, which is unreferenced in this 
program. Positions 17-20 contain a DICE output control functions that positions 
the cursor at line 2, position 1. (See the current version of the ICAM user guide, 
UP-8194). | 

30-36 Heading information is displayed. 

37 The cursor is positioned at line 3, position 1. 

38 The 800-character array is displayed using ‘blank after’. 


UP-8614 Rev. 1 SPERRY UNIVAC OS/3 C-11 
IMS 90 APPLICATIONS 


C.5. IMS 90 EXECUTION 


Finally, the IMS 90 load module IS1 is executed. Figure C-9 shows the job stream 
required to execute IMS 90 (IMS 90 start-up). Do not confuse this execution of the 
configured IMS 90 load module with execution of the RPG Il action program. Remember, 
the action program LSTLIM is executed whenever the transaction code STK and new lower 
and upper limits are keyed in at the terminal for a search of the STOCKS file. 


NOTE: 


The operator must load ICAM by typing in the MCPNAME (C5 tn this case) on. the system 
console before executing the IMS 90 load module. 


The first device assignments are for the printer, IMS 90 files, and user logical file. Note 
that after the first run the EXT cards should be removed. The next device assignments are 
for allocating space for disk queue files. Ultimately, the EXEC statement executes the 
configured IMS 90 load module IS1. Note also that the name on the EXEC statement must 
agree with the name on the LOADM parameter of the IMSCONF jproc. 


JOB IMS, ,14608,14999,4 

DVC ! LFD PRNTR 

DVC VOL REL#58 // NAMEREC // LFD NAMEREC 
DVC VOL REL@59 // AUDFILE // LFD AUDFILE 
DVC VOL RELO58 // CONDATA // LFD CONDATA 
DVC VOL REL959 // DISC1 // LFD STOCKS 
DVC VOL RELO59 

EXT 54 STb« 2 


LBL DQFILEL // LFD DQFILEIL,, 
DVC 64 // VOL RELO59 

EXT S$T,C,0,BLK,(256, 698) 

LBL TCIDTF // LFD TCIDTF,2,INIT 
OPTION DUMP 

EXEC IS$1 


FIN 





*Remove this card after first run. 


_ Figure C—9. Execution of Configured IMS 90 
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C.6. EXECUTING THE RPG II ACTION PROGRAM 


By following this step-by-step process from ICAM network generation to IMS 90 execution, 
the user prepares the system for the online execution of RPG Il action program. 


The RPG Ii action program LSTLIM displays the records of an indexed user logical file 
between the limits specified by the terminal operator. Each UNISCOPE 200 screen 
contains 10 records except the last screen, which may contain fewer records. 


LSTLIM references two IMS 90 interface areas, the IMA and OMA, as well as one user 
logical disk file, STOCKS, configured as an ISAM sequential file. The STOCKS file contains 
stock market information which is accessed by a 3-character stock symbol (alphanumeric 
key). 


The terminal operator executes the LSTLIM action program when he enters the configured 
transaction code (STK) followed by a 3-character key for the lower limit and a 3-character 
key for the upper limit. Records from the STOCKS file within the requested limits are 
displayed in sequence by key, 10 at a time, until the upper limit is reached. 


Figure C-10 shows the user’s transaction code, STK, the lower and upper key limits 
requested from the STOCKS logical file (line 1), and the 10-record screen display from a 
full array (lines 3-12, screen 1) and from a partially filled array (lines 2-5, screen 2). 


When more records exist for the specified key range, the MESSAGE WAIT indicator lights 
at the terminal, and the user must press the MESSAGE WAITING key to receive the 
additional records within the specified limits. 


1 STK BAM NWA 
2 SYMBOL NAME RANGE PRICE CHANGE %CHANGE EXCHANGE 
3 BAM AAACO Li 97 25 1/2 + 1/4 +6.9 NYSE 
4 BGH BBBCO 6é— 39 38 1/4 +2 +55 OTC 
5 CAU cccco 46—181 176 3/4 +1 1/4 +9.7 NYSE 
6 CAT DDDCO 18—69 58 1/4 +3 3/8 +6.1 NYSE 
7 DAP EEECO I— 4 3 1/2 + 1/4 +7.6 OTC 
8 DEC FFFCO / ee ad 4 ) 8.8 NYSE 
g EA GGGCO 5— 16 15 3/8 42.5 AMEX 
10 EEC HHHCO 23— 42 37 1/2 41.3 NYSE 
11 FOR 111C0 4— 14 19 5/8 +6.4 OTC 
12 GEN JJJCO j=. 4 1/8 —14.2 OTC 





SYMBOL RANGE CHANGE %CHANGE EXCHANGE 
HWP 22— 56 — 1/8 —1.38 NYSE 


MAN 58—1298 — 5/8 —§.5 NYSE 
MIC 158—272 nts +2.6 NYSE 
NWA l— 3 7 ee a +21.9 OTC 


on f G RO pe 





Figure C—10. Sample Screen Displays of Simple Transaction Requesting Records From STOCKS File 
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Appendix D. IMS 90 Internal Tables 


The following single-thread and multithread IMS 90 internal thread control blocks (THCB) 
and terminal control tables (TCT), Figures D-1 through D-3, may be used with an edited 
snap dump to further assist the user in determining and solving software problems. 


The snap dump lists areas such as the PIB, IMA, WA, OMA, CDA, THCB, and TCT. By 
examining the following figures, the user can associate the single-thread or multithread 
DSECT for thread control blocks or terminal control tables with those areas shown in the 
snap dump. 
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2T#0FHCB OSECT 


+ 

# THREAD CONTROL BLOCK / SYSTEM INFORMATION SLOCK 

+ 

* THREAD CONTROL SECTION 

= 

+ 

7 INSERTED EQU°S TO MATCH OS/7 NAMES 

* 

ZTSIPIBA EQU * 

ZT#HPIBA DS A PROGRAM INFORMATION BLOCK ADDR 
ZTSTtTIMA EQu % 

ZTRHIMA OS r INPUT MESSAGE AREA AODGR 

ZTaTwA Ecu % 

ZTSHwA oS A WORK AREA ADDR 

ZT#TOMA EQU * 

ZT#HOMA OS A OUTPUT MESSAGE AREA ADDR 
ZT#tcDA EQU + 

ZT#HCDA OS A CONTINUITY DATA AREA ADOR 
ZTSTORMA EQU * 

ZT#HORA ODS A DEFINED RECORD AREA ADDR 
ZT#ODREC EQuU * 

ZT#HODRA DS F CATA DEFINITION RECORD AOOR 
ZTRSUBFL EQU * 

ZTS#HOFA DS F DEFINED FILE/SU3FILE PKT ACDR 
ZT#TF aM = EQU € 

ZT#HFAM DS XL 16 FILE ALLOCATION MAP 
ZT#HNUMF EQU *-ZTSHF AM FILE ALLOCATION MAP .ENGTH 
ZTRTATA EQU * , 
2T@HATA DS F ACTION CONTROL REC PTR 
ZT#TPTA EQU + 

ZT#HPTA DS F PROG CONTROL TABLE REC PTR 
ZT#TPTAL OS F 

ZT#TTTA EQuU + 

ZT#WHTTA OS F TER4 CONTROL TAB REC PTR 
ZT#HIOAY OS F START OF VARIABLE 3/0 AREA 
ZT#HPLA OS F PROSRAM LOAD AREA ADDRESS 
ZT#HBIQP OS F BYPASS INTERRUPT QUEUE PIR 
+ 

* EQUATES FOR 1ST SYTE OF Z2TRHSIQP 

ZBSSOLSH ECU x* 08° SHUTDOWN IN PROCESS 
ZBASOLAS EQu x*o4* AUTOMATIC STATUS 

ZB#SOLCO EQu x°92° ZZUP/Z2Z2UmuN COMMAND OUTSTANDING 
ZBRSOLST FQU x*ore SHUTDOWN TIMER © 
¥* 

ZTHHBIQiL OS KL BYPASSED INTERRUPT QUEUE LENGTH 
ZARUSER ECU * 

ZT#USER DC K*o* « USER FLAG 

* 

* MUST ALWAYS BE ON ODD SYTE SOUNDARY 

t 

* 60 - I40 HAS OCCURRED 

* 4&9 - INITI@L SETTING FOR USER 
* CO - IMS ACTIVE 

* - COUNT FOR TGTAL TIME 
ZTATIND EQU * 

ZT#HIND DS Kil CONTROL INDICATORS 

= 

* EQUATES FOR ZTSHIND 

x 

ZTHHINSP EGU x* ans SNAP INDICATOR 

ZT#HINER CQU Ktace ERROR RETURN 

ZT#HINDI EQU K*2ne DELAYED INTERNAL SUCCESSION 
ZT#HINEO ECU x*1G° EXPLICIT OUTPUT 

ZTRHINEX EgU x*Ga* EXTERNAL SUCCE SSION 

ZTSHINCN E£QU x*O4° CANCELLED 

ZTFHINIR EGU x*o2* INTERNAL REQUEST TO FILE M6MT 
ZTH#HINUP FQU x*o1* UPOATE PERFORMED BY THIS ACTION 
* 

ZTHSYIND DS Kil CONTROL INDICATORS 
ZTSILIST FQu x*sn* INTERRUPT LIST IF SET 
ZT#TOMRD =QU xeane - IF GN INDICATES READ FROM TOMFOLE 
ZT#TRSD EGU x*2c° « RESEND = NO 

ZTH#UTOUT EQu x*ice USER TIM& QT 

ZTHESETL EQu x*e* 

ZT#USETK ECU K°*04* USE THE TEXT IN OMA ALTHOUGH TRANS WAS CNC 
ZT#ZZOPN EQU K*O2" INGICATES 40 weRITE 220PN TERMe RECORD 
ZT#PSSK OS oF 

* 

* FILE MANAGEMENT ENTRIES 

*x 

ZTMIFC FQu * 

ZT#HFC DS F BYTE & :# OF PARAMS) 

* BYTE 3 = FUNCTION CODE 


een 


Figure D—1. Single-thread Thread Control Block (THCB} (Part 1 of 2) 
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 Z7T#TUPDA EQu * 

ZTSHUPDA DS F UNPROTECTED OTF ADOR 
ZT#ICR EQuU + 
ZT#HRPLA DS F PARAM LIST ADOR 
ZT#TFWA EQU +. 
ZTSHF MA §6OS 3A FILE MGMT WORK AREA 
ZT#DMSL OS A TCT ADOR OF OMS RUN-UNIT 
ZT#0mCA OS A DMS - DMCA ADDRESS 
. . 
* SAVE AREAS 
* 
* 
y 
ZT#HSADM DS 16F DATA MANAGEMENT SAVE AREA 
ZT#HSAIR DS LSF INTERNAL REQUEST SAVE AREA 
= 
4 SySTEM INFORMATION SECTION 
= 
ZBaSTIDT BS F TRANSACTION CODE TABLE 
ZB&SACT DS F ACTION CONTROL TABLE 
ZBSSPCT DS F PROGRAM CONTROL TABLE 
ZB@SFCTI OS F FILE CONTROL TABLE INDEX 
ZB#SDCTI OS F DEF FILE CONTROL TABLE 
ZBSSAVAL DS F AVAILABLE LIST ADDRESS 
ZBSSTCS DS F TERM. CONTROL SECTION 
ZBaSIMB OS F INPUT MESSAGE BUFFER 
ZB@SIOAE DS F 1/0 AREA END ADDR 
ZBSSMLL OS H STANDARD MESSAGE LINE LENGTH 
ZB#SHNL OS H STANDARD MESSAGE NUMBER OF LINES 
ZBeSINBLK OS H INPUT MESSAGE BUFFER LENGTH 
ZBSSTOF DS XL1 « USER TLMEOUT FLAG 
ZBESOLOF DS XL 2 CONTROL INDICATORS FOR guoiT 
s 
* EQUATES FOR ZB#SOLOF 
ZBeESOLUP EQU x*8O* UPDATING PERMITTED 
ZBSSOLAI EQU x*age AUDIT MODULE INC UUDED 
% (BEF IMAGES, TR FILES} 
ZB#SOLRD EQu x*20° ROLLBACK PROGRAM / FILE DOWN 
ZBaeSOLSU EQU K*10* SUPPRESS UPDATES 
ZBeSOLTB £QU x*08* BEFORE IMAGES TRACED 
ZBSSOLTA EQu x°04° AFTER IMAGES TRACED 
ZBSSOLTI EQU K*gz* INPUT MESSAGES TRACED 
ZBSSOLTE EQuU x*O) * 1/0 ERROR TRACE FILE 
b 

DS OF 
* 
ZBSFLG1 OS x « FLAG] OF STARTUP 
ZB#STRIN EQU x*aoe e STARTUP ACTIVE 
ZBRSTCRSH EQU x*ag* »*TRCF ILE=CRASH 
ZBSTEXT EQU K*20° o*TRCF ILE=EXT 
ZB9FLG2 OS XK eFLAG FOR TOMFILE _ 
-ZBSTOMUP EQU x*ao* « TOMFILE CONF IGURED 
ZBSTOMER EQU x*o91° « ERROR ON TOM FILE 
ZBSTOMNE EQU x°02* - DO NOT TRACE TOMFILE 
ZB82FLG3 DS x eFLAG FOR TYPE OF RESTART 
ZBSINDCL EOU x*o1® oS TART=CLE AN 
ZBSINDWA EQU x*G2* eS TART=WARM 
ZB#INDCO EQu x*o4° eSTART=COLD 
ZB#FL 64 OS x OMS FLAG BYTE 
ZBSIMSOM EQU x*s0° IMS HAS MADE A REQUEST TO DMS 
ZB#0MS00 EQU x*ag* OMS HAS TERMINATED 
ZP#OMSRU EQU x*26° OMS RUN-UNIT EXISTS 
ZB#IMSNA EOU xe1ce IMS NOT ALLOWED ACCESS TO OMS 
ZBEDMSNA EQU x*9B8°* OMS IS NOT THERE 
ZBaF. 65 OS Xil 
ZBSSFSEN EQuU x*208 SFS ENABLED 
ZB8GL8 EQu x*98°* GLOBAL NETWORK 
ZBSDED EQU K*O4® DEDICATED NE THORK 

DS XL 3 UNUSED 
ZBRLPCT DS F LAST PCY ADDRESS 
ZBR_AST OS F LAST ACT ADORESS 
ZBfLAD DS F LAST LOAD AREA ADDRESS 
ZBMNLST DS 4 INTLISTIN VALUE 

DoS Xi 2 UNUSED 
ZCACCA DS F CCA NAME 
ZC#_OCAP DS F LOCAP NAME 
ZOMTHFIN DS oF - THIS TAG MUST STAY AT END 
ZT#HLEN EQU *-ZTaOTHCB LENGTH OF THCB 
ZT#TLEN EQU ZT#HLEN 

toe, CSECT 
EJECT 
End 


Figure D—1. Single-thread Thread Control Block ( THCB) (Part 2 of 2) | 
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7CaeDTCT oOSECT 


ZCaLINK DS F 

ZCaTID DS Xu4 

ZCaTAL DS F 

e 

ZCaTALT OS F 

ZCaTfTTa OS F 

@ OS/4 USES 7CaTQS & 
ORG ZCBTTTA 

ZCaTtQs DS -H 

ZCallC 0S H 

td] 

ZCaTESR 0S F 

ZCaTCOL OS H 

ZCaTTCM DS H 

ZCaTCM EQu ZC8TTCM 

ZCaTLN 0S Xl 

ZCaTIST: OS XL5 

ZCuTST Equ ZCRTTST 
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®eee TERMINAL CONTROL TABLE RECORD #080 


ACT LINK TO NEXT TCT IN QUEUE 
TERMINAL ID 
REL ADDR ALTERNATE TCT (05/4) 

REL ADDR SOURCE [TCT (0S/3)} 
REL ADDR ALTERNATE TCT (05/3) 
CORRESPONDING TTT ADDRESS 
ZCaTiIc IN PLACE OF ZCaTTA 


OISPL To CAM TERMINAL TABLE 
TOTAL TRANSACTION INPUTS 


Succ acT REL ADDR = ROLLBACK 
CONTINUITY DATA LENGTH 
TERMINAL COMMAND COUNT 

OS/4 TAG 

LINE NUMBER 

STATUS BYTES 

0S/4 TAG 


® EQUATES FOR ZCaTTST/7CaTST 


* 
ZCaTTILST Equ 
ZCattTtTmaD EQU 
ZCeTTUM EQU 
ZCaTTOWN EQu 
ZCaRTTHLD EQu 


2¢aTtTut EQu 


ZCeTMWR EQU 
ZCaTmMTIC EQU 
ZCaTOMw EQqu 
® 


ZCaTSTil EQU 
e 


° EQUATES FOR ZCa#TsSTl 


td 

ZCuTTim Equ 
ZCaTTMT EQU 
ZCaeTALTS EQU 
ZCaTTRC EQu 
ZCaTTmMwsS EqQu 
ZCuaeTTBTH EQu 
ZCaTTRP EQU 
ZCaTTMS EQU 
2 

ZCaeTST2 Ew 
ZCeTPRSF EQu 
@ 


° EQUATES FOR ZCaTST2 


* 

ZCxTTUNS EQu 
ZCaeTTREL EQu 
ZCaTPRMQ EQU 
ZCaTPRMP EQu 
ZCaTISTA EQu 
ZCa#TCONT EQu 
ZCaTOELN EQU 
ZCa#TOIQ EQu 
td 

ZCa2IST3 EQu 
td] 

e EQUATES 
® 

ZCu2TITOR EQvu 
ZCaTTQNE EQU 
ZCaTHORS EQu 
ZCaTION EQU 
7CuTIGM EQu 
ZCaCOIP EQU 
ZCRITINRDY EQU 
ZCeTUNAC EQu 
. 

s 

ZCeIYST4Y EQu 
* EQUATES 
s 

ZCBERMEX EQuU 
7CaSFSRB EQu 
ZCaABTDY EQu 


x*8Q" 
x*4o8 
x20" 
xe10° 


-xeo6? 


x04? 
X*0O2? 
XeOl? 
xeol° 


ZC#TST+1 | 


x¢8or 
Kedge 
20° 
xe1o° 
x*og¢ 
xO4" 
x*"*O2* 
xeO1t 


LAST TCT 

TEST MODE 

URGENT MESSAGE, ACTION 

TERMINAL DOWN 

HOLD TERMINAL 

URGENT TERMINAL . | 
MSG walt (FOR ZZ1ST) RECEIVED 
MWRITE FOR ZZTST (SINLGE THRE«|D) 
OUTSTANDING MWRITE (MULTI THREAD) 


INTERACTIVE MODE 
MASTER TERMINAL 
ALTERNATE TERM SPECIFIED 
ROLLBACK COMPLETE 
IMS SENT MSG WAIT 
BATCH TERMENAL 
ROLLBACK IN PROCESS 
MSG TO ORIG TERM SENT 


ZCB8TSTI+1,1 


ZC8&TST2 


x*ag? 
x4 
x*208 
xeioe 
x*Qgee 
x°o4e 
x*0O2° 
x*O1° 


MWRITE ISSUED FROM ZOSUNSMT MODULE 
RELEASE BUFFER aT MWwRITE COMPL 
MSG IN QUEUE 
MSG IN PROCESS 
SEND AUTO STATUS MESSAG 
CONTINUQUS OUTPUT REQUESTED 
DEL NOTICE = ACTION TO BE SCHED 


OUTPUT GENERATED FOR INPUT QUFU;ING 


ZCRTST2¢1,1 


FOR ZCaTsTt3 


x'80* 
x'40? 
x*20° 
xeloe 
x*OB8* 
x*-o4e 
x*O2° 
xeO1° 


DISCONNECT REQUESTED (S/T) 
TERMINAL’S LOW QUEUE NOT EMPTY 
OUTPUT HEADER SAVED 
INTERNAL DELIVERY NOTICE 
IMS GENERATED ERROR MSG 
CONTINUOUS OUTPUT IN PROCESS (m/T} 
NO IMS READY MSG TO THIS TERMINAL 
SEND UNSOLICITED OUTPUT {NOICaTuR 


FOR SwITCHED MESSAGES AT ACTION END 


ZceTST3+¢1,! 


FOR ZCxTST4 


X*8O* A/M GENERATED ERROR MSG, 


x48 
x*20¢ 


REBUILD ALLOWED BY a/P 
ABORT OYNAMIC SESSION 


Figure D—2. Single-thread and Multithread Terminal Control Table (TCT) (Part 1 of 2) 
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Eu Xeig® ABORT TERM wINDOW 


ZCa2SIGN EQu x'Oge SIGN ON FOR DYNAMIC SESSION 
ZCaTSTS EQuU ZC#8TST4+1 21 DMS FLAGS 
ZCHeIMPRT EQu x*s8o? ESSUED |[MPACT FOR ACTION 
ZCaDEPRT EQU x4" ACTION ISSUFD DEPART 
2CxOMSUP EQu xe20° ISSUED DSM OPEN FOR UPDATE 
ZCHOMSDR EQu x*10% DMS REQUEST VIA DeRaMe 
ZCeDMSRO EQU x*O8* OMS FORCED DEPART wITH ROLLBACK 
ZCeOMSUB EQU xe'aqe DMS RUN UNIT UNBOUND 
*# THE FOLLOWING STATUS BYTE TAGS ARE NOT CLEARED WHEN A GLOBAL 
* NETWORK DYNAMIC TERMINAL OCES A SSSOFF 
* ZCHTILST 
* ZCHeTTuUtT 
* ZCHTIMT 
* ZCH# INROY 
* ZCHTUNAC 
* ZCaATTRKI 
% 
DS x UNUSED 
sd 
ZCaTQE 0S F CaNCEL tLINK 
ZCaPRFT OS F DISPL TO PROCESS FILE TABLE 
ZCePQCNT DOS H PROCESS QUEUE COUNT 
ZCHMQCENT OS xu LAST I1Cam SVC 
ZCaTDELS OS XL} DELIVERY NOTICE STATUS 
ZCaLQCNF OS H LOW QUEUE COUNT 
ZCaTIN oS H TOTAL INPUT COUNT 
ZCaTOC DS H ToTalL OUTPUT COUNT 
7ZCax TON OS F TIMER LINK 
7Ca2lBF DS H DISPL To 1ST SLOT OF INPUT MSG 
ZCa#IML DS a INPUT MESSAGE LENGTH 
2CR0BF oS H DISPL TO 1SY SLOT OF OUTPUT MSG 
ZCaOME 0S Ho OUTPUT MESSAGE LENGTH 
e OS/3 SINGLE THREAD SySTEM USES ZCRCOSEW FOR C40 SEQUENCE COUNT 
ZC RCOSE@ OS a C/O SEQ COUNT {08/3 Sele) 
® 
ZCaTBF Equ ZCRCOSEQ TIMER BUFFER ADOR (OS/3 MeTe) 
Z7Ca#TML DS H TIMER MESSAGE LENGTH (05/3 Mete,) 
ZCHTDELC DS XL4 USER CONTINUOUS OUTPUT CODE 
ZCHSFSTC DS A SFS TERMINAL CLASS ENTRY AUDR 
7ZCeSFSFN DS CL8 SFS FORMAT NAME 
ZCe2SESID DS F SESSION 1D 
7CaTTRID DS CLs TRANS I10 ¢CINITIAL DATE/TIME) 
7CaTRID EQU ZCETTRID O5/4 TAG 
ZCROLCNT DS H IMC DEADLOCK DETECTION COUNT 
ZCeTCB DS A THREAD CONTROL SLOCK AODR 
ZCHILI DS 45 TRANS LOCK INDICATOR 
7ZCaTAUM DS 4 AUDITED UPDATE mAP 


@@e ZJCaTLE AND 


ZC#TAUM MUST AGREE wITH ZT#TNUMF IN THE THCB8 


ZCaTTEXT OS CLS TRANSLATED TERM CMD/TRANS CODE 
ZCaTCOOE EQu ZC®TTEXT OS/4 TAG 
ZCaTOORC OS CL DDR NAME 1D CHAR (HIGH BYTE @ X*FD?)} 


eee THE ABOVE FIELD IS OFFENEO IN OS/4 BUT NOT TAGGED 





ZCxuTODRN DS CL7 DATA DEF REC NAME 
7CaeTOFN ODS CL? DEFINED FILE NAME . 
ZCaTES DS F SuUCC ACT RECORD RELATIVE AUODR 
e MULTI@THREAO SYSTEMS USE ZC#ES & ZCRCDOC IN PLACE OF ZcCRTES 
ORG ZCRTES 
ZCH#ES DS H SuCC ACT RECORD RELATIVE AUDR 
ZCaCDL 0S H CONTINUITY DATA LENGTH 
* ; 
ZCeWwal DS H WORK AREA INC 
ZCxa2 CO! OS Hi CONTINUITY DATA AREA INC 
ZCaTTIN OS XL 1 TCT RECORD NUMBER 
DS XLl UNUSED 
ZCaTINT OS H TOTAL TRANSACTION INPUTS 
% MULTI=<THREAD USES 7C#COR & ZCBCES INSTEAD OF ZCRTTIN & ZCaTINnT 
ORG ZCBTTTN © 
ZCeCOR OS H TCT RECORD NUMBER 
ZCaCES DS H SUCC ACT REL ADDR = ROLLBACK 
ZCaxSCFR DS XL4 COUNT FIELD FOR ROLLBACK 
¢ 
7ZCaeTTIR OS XLII TERM IND FOR ACTION PRUG USING ROLLBACK 
ZCaTFIR Ew ZC&8TTIR OS/4 TAG 
ORG ZC#TIR 
ZCaTRwWa DS F TRACE wORK AREA 
ZCaFBPA DS H * FIRST BLOCK OF PARTITION 
Z7CaCBPA OS H ® CURRENTLY ACCESSED BLOCK 
7ZCaLBPA OS H ® LAST pLOCK OF PARTITION 
ZCeNRBCB DS H @# OF REMeBYTES IN CURR. BLOCK 
° 
ZCrTLNAM DS cL4 LINE NAME 
s 
ZCaTLEN EQU *#=ZCROTCT 
&GSYSECT CSECT : 
END 


Figure D—2. Single-thread and Multithread Terminal Control Table (TCT} (Part 2 of 2) 
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ZT#OTHCB OSECT & 
ZTHTHOPT DS F « NEXT THREAD IN QUEUE POINTER 
ZT#NTHCB DOS F e NEXT THRE&O FOR SCHEDULING 
ZT#IHURF OS x « URGENT FLAG O - ROUTINE 
ZTS8THROF OS x « THREAD READY FiaG 1 - READY 
ZTeOWAIT OS Ox BIT O INITIAL THREAD WAIT FLAG ~— WAIT 
ZT#REGRS DS x BIT 7 RESTORE REGISTER FLAG O - yES 
ZTaIEce3 OS x BI¥ O CANCEL FLAG 4 - CANCEL 
* BIT 2 OUTPUT MESSAGE GENERATED BY Z6 8MTMSO 
i BIT 3 INTERNAL CANCEL INITIATED 
* BIT 7 IECB FLAG 1 -~ 3WOROD 
ZT#THS¥R OS F « THREAD SAVE AREA REGISTER 
ZTSTHRAD DS F « THREAD RETURN ADDRESS 
ZYSIPIBA DS A PROGRAM INFORMATION BLOCK ADDR 
ZTaTIMA OS A INPUT MESSAGE AREA ADOR 
ZTRTUA ps A WORK AREA AODR 
ZTaTOMA DS A OUTPUT MESSAGE AREA ADDR 
ZTSTCDA OS A CONTINULTY DATA AREA ADOR 
ZT#TORMA DS A DEFINED RECORD AREA ADDR 
ZT#SDOREC OS A DATA DEFINITION RECORD ADGR 
ZTSSUBFL DS A DEFINED FILE SUB-FILE OESC ADOR 
ZTatFam OS aF FILE ALLOCATION MAP 
ZTSTNUMF EQU *e-ZTOTFAM FILE g~LLOCATION MAP LENGTH 
ZT#TATA OS A ACTION CONTROL TABLE REC ORO ADOR 
ZTaTPTaA OS r PROGRAM CONTROL TASILE RECORD ADDR 
ZT#TPTAL DS F 
Z¥aTIITA DOS A TERMINAL CONTROL TABLE RECORD ADOR 
ZTaTing oS A INPUT MSG BUFFER AOOR 
ZTaveENIT OS A FOIT TABLE ADDR 
ZT#TRIO OS c.8 TRANSACTION ID 
ZT#TIND DS KUL CONTROL INDICATORS 
* BIT Oo TERMINATION TYPE G NORMAL 
€ 1 ABNORMAL 
* BIT 2 ERROR RETURN 0 NO 
+ 1 YES 
a BIt 3-4 INTERNAL MESSAGE CONTROL: 
* oo END ACTION OR END TRANSACTION 
* ol EXPLICIT OUTPUT 
* 10 DELAYED INTERNAL SUCCESSION 
+ ll CANCELLED 
* BIT Ss INTERNAL REQUEST INDIC FOR FM 
* rs] NO 
* i YES 
* BIT 6 OUTPUT IN PROCESS 
* BIT F OUTPUT WAITED 
ZTaTERa ODS x ERROR CODE NUMBER 
ZT#TESs DS H RELATIVE ACT RECORD ADOR 
* FILE MANAGEMENT ENTRIES 
* PARAMETER LIST FOR SUBTASK 
ZTRIBA oS A . BEGIN ADOR 
ZT#TIRPLA OS A REQUEST PARAM LIST ADOR 
ZTaTFC DS A BYTE 0 -— #& OF PARAMS IN LIST 
* BYTE 3 —- FUNCTION CODE 
ZTATUPDA DS A UNPROTECTED OTF ADOR 
ZTAHICR os A COVER REG 
* OTHER 
Z2T#TFMA OS 3A WORK AREA 
ZTaTSAVI DS ALA SAVE AREA 1 
ZTH#TSAV2 DS LIA 
ZT#SAVS EQU ZTBTSAW2 SAVE AREA S 
ZTRSAVE6 EQU ZTSSAVS*40 
oS 7F°O° 
ZTAaTSAVS DS 18a SAVE AREA & 
ZTHTSAV3 OS LlA SAVE AREA 3 
ZARPSSK DS oF 
ZT#TFLA DS F REQUIRED BY IRAM 
ZT#TF1 DS F APPL. MANAG. 
ZVaIF2 DS F FLAG BYTE 
ZT#SYIND EQuU ZTaTF2 FLAGS 
ZTHTOMRD £QU x*age INDICATES TOM READ 
ZTSZZOPN EQU X*O04%* INDICATES TO WRITE ZZ0PN TERM. RECORD 
ZT@#DMSL DS A TCT ADOR OF OMS RUN-UNIT 
ZTSOMCA OS A DMS ~ DMCA ADDRESS 
ZTe#SIBA DS F SIB ADDRESS 
DS OF 
ZT#TLEN EQU #-ZTSOTHCE LENGIH OF CONTROL BLOCK 
ESYSECT CSECT 
END 


Figure D—3. Multithread Thread Control Block {THCB) 
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Appendix E. Device Independent 
Control Expressions 


E.1. GENERAL 


You use device independent control expressions (DICE sequences) to format input and 
output messages being handled by your action program. These codes are needed to control 
various operations, such as cursor positioning and carriage return, on a terminal screen. 


Appendix E supplies all DICE sequences and their interpretations, describes how to use 
them in formatting your messages in your action programs, and discusses the DICE 
macroinstructions you can use in BAL user action programs to create the DICE sequences. 


E.2. USING DICE TO FORMAT MESSAGES 


For output, your action program can use either of two methods to control the format of a 
message displayed at a terminal. 


1. By embedding format control characters, the message text is directed to each specific 
terminal. Obviously, if you do this, your program must include a different formatting 
routine for each type of terminal; this is illustrated in the following diagram: 
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OUTPUT TEXT AND CONTROL CHARACTERS ® 





REMOTE 










USER 
DEVICE 
PROGRAM HANDLERS 
LEGEND: 


Ws 





i 


Terminal-Oriented 
Control Characters 


By embedding DICE sequences, the control of format for various types of terminals 
and auxiliary devices is simplified. The remote device handler (RDH) converts DICE 
sequences to control characters for each destination terminal. Some of the control 
character functions are: 


line feed — cursor movement to the first space of a new line; 
form feed - cursor to the home position of a new page; 
Carriage return — cursor to the beginning of the same line; or 


cursor movement to a specific row and column on a display. 


You can place DICE sequence anywhere in a message to accomplish the control you 
want. As you can see by the following illustration, formatting is easier when you use 
DICE. 
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OUTPUT TEXT AND DICE 


USER REMOTE 


DEVICE 
PR 
conene HANDLERS 








TEXT i 














DICE Characters 


Termina!-Oriented 
Control Characters 





For input, control characters received in a message are converted into DICE sequences by 
the RDH. For certain terminals, your program can analyze these DICE sequences to 
determine cursor position. In addition, input DICE is handy for message switch application 
because control characters in each input message are converted to DICE sequences. The 
RDH converts these sequences into the appropriate control characters for the destination 
terminal. 


You can turn DICE on or off at network definition time with the DICE operand on to the TERM 
macroinstruction. 


ee oret) 


The default is DICE=(ON). 


1. DICE=(ON) tells RDHs to create input DICE according to your input terminal cursor 
movements; DICE are created automatically. 


For UNISCOPE 100/200, UTS 400, and UTS 4000, the ICAM remote device handler 

passes the start of text character (STX) to your program as the first byte of data. For 

example, in a message containing a start of entry character (RS), the following data is 
@ received in the text portion of your input work area: 


E Vv Y XK N S R 
S T Us| S___rest-of-text 
C L 


S 


1 
X 
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End of text characters (ETX) are always removed by the remote device handlers; they 
are never supplied to your program as text. 


2. DICE=(OFF) tells the RDHs not to create input DICE. 
For UNISCOPE 100/200, UTS 400, and UTS 4000, the start of text character (STX) is 
Suppressed by the remote device handler, and control character sequences are 
converted to DICE sequences. For example, in a message containing a start of entry 
character (RS), the following text is received in the text portion of your work area: 


4-character-dice-sequence R rest-of-text 
S 


End of text characters (ETX) are always removed by the remote device handlers; they 
are never supplied to your program as text. 


See the OS/3 fundamentals of ICAM, UP-8194 (current version), for a detailed example of 
input DICE creation. 
E.2.1. Format of DICE Sequences 


The format of a DICE sequence is as follows: 


Format: 
select function 
n field 
character code 
where: 


select character 
ls a hexadecimal character (10,,) designating the start of a DICE sequence. This 
character, a data link escape (DLE) control character in EBCDIC, must be used 
only to designate the start of a DICE sequence. 


function code 
Defines the device control sequence that is recognized by the RDHs on input. On 
output, this code is a 1-byte field defining the operation to be performed on the 
text message. DICE function codes are listed in Table E-1. 


m field and na field 
These fields are treated as parameters to the DICE function code: their actual 
definition varies and is determined by the individual DICE macroinstruction. 
Generally, m relates to vertical positioning and n applies to horizontal 
positioning. 
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These fields may be expressed in absolute values (m, and n,) or relative 
displacement values (m, and n,) in Table E-1. The absolute values align the text 
message to the actual location (row and column) on a page or screen. The 
relative displacement values give a relative location from the present position of 
the cursor, e.g., move cursor 2 rows down and to column 1. If you choose to use 
DICE macroinstructions, these parameters must be specified. 


E.2.2. DICE Macroinstructions 


DICE macroinstructions let you create DICE sequences (DICE constants) in the same way 
you would create constants in your program; when the assembler expands a DICE 
macroinstruction, your program creates a constant at that location. 


On output, when your program is ready to send a message, it moves the DICE constants 
created from the DICE macroinstructions into the appropriate places in your message 
before it issues the output request. The RDH converts the DICE constants into the 
corresponding control characters to produce the necessary positioning. 


On input, DICE sequences are automatically created by the RDHs unless you specify the 
DICE=(OFF) parameter in your network definition. Table 2-5 lists the DICE 
macroinstructions, function code generated, and m and n coordinates as they apply to 
particular devices on input and output. 
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You must specify m and n coordinates in your program according to the absolute and 
relative values expressed in Table E-1.m, andn, are absolute values of m and n; m, and 
n, are relative displacements of m and n. For CRT terminals, the home position is (mg, Nn) 
= (1,1). For character- or page-oriented devices that allow position to top of form, the top- 
of-form position is (m,,n 4) = (1,1). 





# Absolute Positions 
Absolute positions of ma and ng may range as follows: 
m, ranges 1 tor 
where: 
r = maximum number of rows (CRT), or maximum number of lines per page. 
n, ranges 1 toc 


where: 


c = maximum number of columns (CRT), or maximum number of character 
positions per line. 


a Relative Displacement 





Relative displacements of m, and n,; may begin at zero and range to the bottom and 
right margin of the screen or page. 


If a value of m or n falls outside of the legal range, that value of m or n will cause the 
following action: 


m, or n, = O is interpreted as m, or n, = 1 


Specifying an absolute or relative value for m or n that is greater than the screen or page 
size Causes unpredictable results. 


E.2.3. DICE Code Generation 
Macroinstructions are provided to generate the DICE codes. 


Format: 






AOPERATIONA 





OPERAND 





[symbol ] dice-macroinstruction 
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Y 
Label: ® 


{symbol ] 





An optional alphanumeric character string, from one to eight characters long, that 
identifies the specific instruction line. 


Operation: 
dice-macroinstruction 
You specify the appropriate name from the macroinstruction column of Table E-1 
for the desired DICE sequence. 
Positional Parameter 1: 
A decimal number (0 to 255) indicating the number of lines or rows the terminal 
should advance before starting output of the message (Table E-1). 
Positional Parameter 2: 
A decimal number (0 to 255) indicating the number of spaces or columns to the right 


the terminal should space before starting output of the message (Table E-1). @ 


Examples: 
1 10 16 

1.] NEWLINE ZO#POS 9,8 

2. | COORDI ZO#COORD 5,18 
1. This DICE sequence causes movement to a new line. 


2. New text will be started at line 5, column 10 due to this DICE. 
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Table E—1. DICE Input/Ouput Commands, Codes, and Device Interpretation (Part 1 of 4) 


DICE Function | Character- Page Printing Communications 
Macro- Function Code oriented CRT Devices Devices Output Printer 
instruction Devices) (n is Not (CoP) 
Interpreted) 


ZO#COORD {Set coordinates | Oli, 





| m and n represent 
N the start-of-entry 

P (SOE) cursor 

U coordinates. 

T 


Move cursor to row (Action is optional. | Action ts optional. 
m and column n. 


4 CH CO 





| ZO#FORM ‘| Forms control 02:6 


4c us — 


Move cursor to row |Top of form and Form feed, line feed, 
advance to line m {and advance to 
(m—1 line feeds) | line m and column 
n (m—1 line feeds 
and n—1 spaces to the 
right) 


—~ CT 4 CO 


ZO#FORMC | Forms control 0316 
with clear 
unprotected 
data 


ac UZ 


Move cursor to row jAction is optional Action Is optional. 
m and column n, 

and clear unpro- 

tected data to 

end of screen. 


s4aocvrnsco 
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Table E—1. DICE Input/Ouput Commands, Codes, and Device Interpretation (Part 2 of 4) @ 


Function Page Printing Communications 
Code | 1/0 CRT Devices Devices Output Printer 
Value (n is Not | (CoP) 

interpreted) 


ZO#POS New line control 04:6 00 | 00 |Carriage return, | Cursor return Not used 
m | n_ {Carriage return, | Move cursor to Advance (m+1} Line feed, followed 
‘| 'ltine feed, fol- beginning of next __ flines. by m line feeds and 
lowed by m line line. Then move n spaces to the 
ZO#POSC New line control 0515 — 
with clear 


feeds and n — {| Cursor m lines right. 
spaces to the |down and n col- 
ZO#CUR Current position 
control 
ZO#CURC Current position 0716 
control 
with clear 








Character- 
oriented 
Devices 


DICE 


Macro- 
instruction 










































right. umns to the right 


Not used 























Line feed, followed 
by m line feeds and 
n spaces to the right 


Same as 04;, ex- 
cept area between 
start and end posi- 
tions is cleared. 


Carriage return, 
line feed, fol- 
lowed by m line 
feeds and n 
spaces to the 
right 





01 End of input card {Not used 






















Insert n spaces if 
nonsignificant space 
suppression is allowed. 
If not, insert n DC3 
characters; m is not 
interpreted. 


m line feeds Move cursor m lines |Advance m ines. 
and n spaces to 


the right 






to the right. 





ae CHOCO |} Ae Ve +c T HCO | an octwaz AacCcTwT HOO YY} AWoCOCv ae Ac wTH CO }y a oD es 
3 i 
= 


Not used 
















m line feeds Advance m lines. 
and n spaces to 


the right 





Insert n spaces if 
nonsignificant space 
suppression is 
allowed. If not, inse 
n DC3 characters; m 
is not interpreted. @ 


Insert n spaces if 
nonsignificant space 
Suppression Is allowed. 
If not, insert n DC3 
Characters; m Is not 
interpreted. 









' 
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Table E—1. DICE Input/Ouput Commands, Codes, and Device Interpretation (Part 3 of 4) 


CRT Devices 



















Page Printing 






DICE 


Character- Communications 


Function 








Macro- Function Code |1/0 oriented Devices Output Printer 
instruction Value Devices (n is Not (coP)@) 
Interpreted) 






00 | 00 Carriage return | Not used Not used 












m line feeds and n 
Spaces to the right. 


mopn Carriage return Move cursor to Advance m lines. 
followed by m_ {beginning of current 

line feeds and j line. Then move 

n spaces to the} cursor m lines down 

right and n columns to 


the right. 
















ZOH#BEG Beginning 081, 
of current 
line control 

ZO#TABS Set tab stop 
at an 
absolute 
position 4 

ZOHFORMA | Forms control 
with clear; 
protected/ 
unprotected 
data 


ZO#ERSLN Frase to OB; 5 
end of line 





Not used 


—~ee i Oo — ee eee Oe ee ee) —_ we ee Toe — 


No line feed, |Set tab stop at row {Advance m lines. Not used 
space ta right. |m and column n. 










SAC THCO, AC TZ—]AcmHCOSO , ACP ]Z— 












Not used Not used 


Move cursor to row Action is optional.) Action is optional. 
m and column n 
and clear pro- 
tected/unprotected 
data to end of 
screen. | 














Not used Not used 


—_—<_“ 2 << —— = «= am Se ee eee 


Cursor does not Advance 0 lines. Not used 
move. Unprotected 
data to the end of a 
line or to the end 
of the first unpro- 
tected field is 
cleared, whichever 
comes first. 





=| 
o> ! 





UP-8614 Rev. 1 SPERRY UNIVAC OS/3 E-10 





IMS 90 APPLICATIONS 


Table E—1. DICE Input/Ouput Commands, Codes, and Device Interpretation (Part 4 of 4) 


NOTES: 


® 


Most character-oriented terminais can be strapped to handle the carriage return (CR) character and the line feed 
(LF) character as follows: 


a CR 
1. print mechanism moves to beginning of the same line; or 
Zz print mechanism moves to the beginning of the same line followed by a line feed. 
e LF | 
1. line feed (no columii change); or 
2. line feed followed by return of the print mechanism to the beginning of the new fine. 


To achieve device independence between terminal types, the character-oriented terminals must use the first option 
for CR and the first option for LF if the device macroinstruction is ZO#CUR or ZO#BEG. 


The first option should be used if the character-oriented terminals are a part of a message switch environment. 


Certain terminals do not have a form feed capability (i.e., some TTY terminals). For these terminals, the DICE 
expressions that specify form feed will result in line feed instead. 


The set coordinates macroinstruction (ZO#COORD) or the forms control with clear macroinstruction (ZO#FORMC), 
when acted upon by character-oriented or page-printing terminals, will vary in its action, depending on the usage 
of the DICE keyword parameter of the TERM macroinstruction at network definition time: 


TERM ...- .DICE=/ {FORMS { ere 
NEWLINE 


lf FORMS is specified, the set coordinates macroinstruction will be interpreted as the forms control 
macroinstruction. 


lf NEWLINE is specified, the set coordinates macroinstruction and the forms control with clear macroinstruction 
will result in a carriage return, line feed for character-oriented terminals, or advance one line for page-oriented 
terminalis; m and n are not interpreted. 


If the DICE parameter is not specified, the default option will be to NEWLINE. 


The UNISCOPE display terminal suppresses nonsignificant spaces on each line (except for the line containing the 
cursor) when text is transmitted to the processor or printed locally on the COP or TP. 


Your program may send data to the UNISCOPE screen containing significant blank segments that inciude the last 
column of the screen. If this data is transmitted from the terminal to the processor or is printed locally on the COP 
or TP, the blank segments must consist of nonspace characters that are nondisplayable. The DC3 character meets 
these qualifications. The ICAM interface provides your program with the capability to prevent nonsignificant space 
suppression on the UNISCOPE dispaly terminal. The ‘current position control with clear’ is the only DICE 
macroinstruction that can be used to perform a clear function if your program is preventing nonsignificant space 
suppression. 


NOTE: 


The ASCIl-to-EBCDIC translation table is modified so that the DC3 character is translated to space 40,, for input 
from the UNISCOPE display terminal. 


When using DICE function code 09,, for setting a tab stop, m=O and n=O will result in a tab stop being placed at 
the current cursor location (no cursor positioning is performed). This applies to UNISCOPE aand UTS 400 devices 
only. For TTYs and DCT 500 terminals, a space character is inserted. 

If m or n is greater than the maximum allowable m or n, action will vary depending on the remote terminal: 


a UNISCOPE display terminals-wraparound will occur on screen. 


a Character-oriented terminals-will give different results depending on the characteristics of the device. 
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E.2.4. Interpretation OF DICE 


When using DICE, your program does not need to be aware of the terminal type. A 
particular DICE denotes the same positioning on any terminal. There are some exceptions 
that result from limitations of the terminal. 


The interpretation of a DICE by the RDH is controlled by the following factors: 


1. 


2. 


3. 


4. 


DICE function code 
DICE m and n fields 
The terminal involved 


The particular device on the terminal being used. 


The ICAM RDHs currently provide device-independent support for three classes of remote 
terminal devices: 


1. 


Hard copy character-oriented devices, such as the SPERRY UNIVAC Data 
Communications Terminal 475 (DCT 475), Data Communications Terminal 500 (DCT 
500), Data Communications Terminal 524 (DCT 524), and Data Communications 
Terminal 1000 (DCT 1000), and TELETYPE* teletypewriter models 28, 32, 33, 35, 37. 


Hard copy page printer type device, such as the SPERRY UNIVAC 1004 Card 
Processor System, Data Communications Terminal 2000 (DCT 2000), and 9200/9300 
Systems, and the IBM 2780. 


CRT-type terminals, such as the UNISCOPE 100 and 200 and the UTS 400 Display 
Terminals. 


Table E-2 defines the primary output device and the primary input device for each terminal 


type. 


Table E—2. DICE Primary Devices 


| Character-oriented terminals | racter-oriented terminals 






*Trademark of Teletype Corporation 
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In addition to the specified primary devices, each terminal has the ability to support one or & 
more auxiliary devices. The auxiliary devices suggested by each terminal are listed in Table 
E-3. : 


Table E—3. DICE Usage for Auxiliary Devices 


Auxiliary Device DICE Usage 


UNISCOPE Tape cassette (TCS) DICE is applied to the COP. (1) 
Communications output printer (COP) 
800 terminal printer (TP) 





























DICE is applied as if the 
output/input is to/from 
the primary device, even 

through it is for the auxiliary 
device. 


DCT 1000 Card reader/card punch 


Paper tape reader/punch 


DCT 500/TTY Paper tape reader/punch 
DCT 524 : Tape cassette (TCS) in paper tape 
read and write only 


Batch terminals Punch 

















DICE is used for end of 
network buffer sentinel. 
No forms control action is 
taken. 







NOTES: 


(1) If the print transparent option is not used, DICE is applied to the UNISCOPE screen even through the output is sent & 
to an auxiliary device of the UNISCOPE terminal. In this case, the format of the data printed on the COP or TP is 
identical to the screen format. Nonsignificant space suppression by the UNISCOPE terminal may have to be 
prevented to keep the formats identical. 


The full capability of DICE cannot be applied to to the COP because of hardware characteristics. All data to a 
UNISCOPE auxiliary device passes through the UNISCOPE terminal. When DICE is applied to the COP, the use of 
print transparent mode means that no carriage returns are transferred to the COP. Line feeds and form feeds take 
a storage position in the UNISCOPE storage and are nondisplayable. These characters are passed to the COP 


where: 

a an LF causes a line feed followed by return of the print mechanism to the beginning of the new line; and 

a an FF causes a page eject and positioning of the print mechanism at the beginning of the first line of the 
form. 


The COP has no tabbing capability. 
These characteristics are reflected in the interpretation of DICE output function codes for the COP as shown in Table E-2. 


For messages sent to a UNISCOPE auxiliary device with transparent transfer, the cursor to home (ESC e) sequence is 
inserted at the beginning of the text by the RDH. 


See 3-3 for more detailed information on the usage of DICE when applied to the COP. 


Q) The contro! characters that are generated from the DICE macroinstructions are always created for the primary 
device of a character-oriented device, even though your program is sending to an auxiliary device. The message 
and these control characters (carriage returns, line feeds, form feeds, and spaces) will be punched/written by the 
output auxiliary device that was specified by your program or was switch-selected by the terminal operator. If the 
punched/written data is later read by the terminal's input auxiliary device, the carriage returns, line feeds, and 
form feeds are converted to input DICE as specified in Table E-1. © 
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Glossary 


A 


action 
The basic unit of work in IMS 90. An action consists of message input, the processing 
of the message by one or more action programs that may access data files, and the 
output of at least one message. 


action program | 
An independent, relocatable program defined to IMS 90 and conforming to the 
programming conventions established by IMS 90. One or more action programs may 
& be executed in an action. 


action scheduling 
A component of application management that initiates and terminates an action 
program and dynamically allocates required and optional main storage areas used by 
an action program. 


activation record 
The working storage area used by a specific action program to process messages and 
transmit information begween IMS 90 and the action program. The activation record 
must include the program information block (PIB) and the input message area (IMA) 
and may optionally include the output message area (OMA), work area (WA), 
continuity data area (CDA), and defined record area (DRA). 


application management 
The major component of IMS 90 that controls the execution of action programs and 
includes action scheduling and file management. 


automatic status messages 
Messages automatically generated by multithread IMS 90 to notify the terminal 
operator of the status of the last input message. 


auxiliary-device-function 
, A 1-byte field within the auxiliary-device-ID field of the OMA which specifies auxiliary 
@ information about this output message. For example, the message is being sent to an 
auxiliary device or is handled as continuous output. 
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auxiliary-device-ID 
A 2-byte field in the OMA which indicates auxiliary information about this output 
message (auxiliary-device-function) and to which device (auxiliary-device-number) the 
message is to be sent if the first byte indicates it is being sent to an auxillary device. 


auxiliary-device-number 
A 1-byte field within the auxiliary-device-ID field of the OMA which specifies the 
device number that corresponds to the logical device number in the CCA network 
definition. 


auxiliary output device 
The two auxiliary output devices supported by IMS 90 for communications are the 
communications output printer (COP) and terminal printer (TP). 


B 


batch transaction processing 
A method of processing groups of transactions entered from cards or a source library 
file instead of an online terminal. This method is useful for testing if an online 
terminal or ICAM is not available, or for performing batches of transactions overnight. 


batch transaction processor | 
An optional component of single and multithread IMS 90 which enables transactions 
to be entered via cards or source library file instead of a display terminal and 
transmits output to the printer file. 


C 


common storage area (CSA) 
An area in main storage containing one or more resident ISAM files, called CSA files. 
Action programs retrieve data from and make updates to the CSA file instead of a disk 
ISAM file, thus reducing disk access. 


communications control area (CCA) 7 
A collection of tables that describe the ICAM communications network: 


configuration 
The process by which the available IMS 90 software is tailored so that the resultant 
IMS 90 package satisfies the needs specified by the user and reflects the user’s 
hardware and software environment. 


continuity data area (CDA) 
An optional main storage area in the activation record in which user-defined data is 
automatically passed from action to action in a transaction. The continuity data is 
written to the continuity data file at the termination of an action and read into main 
storage when the successor action is scheduled. 
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continuous output 
A continuous series of output messages transmitted to a terminal without intervening 
input messages. 


data definition language 
A COBOL-like language used to describe defined files accessed by user action 
programs or UNIQUE through defined record management. 


data definition processor 
That module of IMS 90 that processes the data definition and writes a data definition 
record into the named record file. 


data definition record 
A record in the named record (NAMEREC) file that contains the description of a 
defined file and related subfiles and is used by defined record management to access 
that defined file or those subfiles. 


data name 
A word that names an entry in the data division of a data definition or COBOL action 
program. 


defined file 
A sequence of defined records in order by their identifiers. 


defined file name 
Name of defined file. 


defined record 
A sequence of items obtained from IMS 90 by UNIQUE and other action programs 
with the execution of a single function call. It is displayed at the terminal by UNIQUE 
in response to a single operator command. IMS 90 composes the record dynamically 
from one or more disk records, according to a user-supplied data definition. 


defined record area | 
An optional main storage area in the activation record used by the defined record 
management portion of IMS 90 if defined files are accessed. 


defined record management 
That module of IMS 90 which retrieves and/or updates defined records for action 
programs. 


defined record name 
That name that identifies a particular type of defined record in a defined file. 


defined record supplement 
Additional items from logical records or repeating groups, other than the source of the 
primary part, that complete a defined record. 
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i hs A 


definition division & 
The third division in the input to the data definition processor. This division describes 
the defined files and the defined records. 


delayed internal succession 
A method of succesion in which one action builds an output message in the OMA 
and queues it aS an input message to a second action without sending the output 
message to the originating terminal. 


delivery notice scheduling | 
The scheduling of a successor action program to receive a 5-byte IMS 90 
acknowledgement message (delivery notice) indicating that an output message has 
been successfully or unsuccessfully delivered to its destination for continuous 
printing. 


detail line 
An output line containing values associated with the item names from the header 
line. The values are from the file being accessed. 


detailed status code 
A 2-byte binary value returned by IMS 90 following a request when the status code 
indicates invalid request, |/O error, or internal message control error. The detailed 
status code supplements the status code by giving more detailed information. 


device-independent-control-expression & 
A 4-byte control sequence used in formatting messages at a terminal and consisting 
of the select character (10,,), a hexadecimal function code, and two hexadecimal 
coordinates defining row and column positions on a terminal. 


dialog 
Interaction between a terminal operator and IMS 90 consisting of a sequence of 
logically related input and output messages. When UNIQUE is used, it begins with an 
OPEN and ends with a CLOSE or another OPEN. 


dialog transaction 
A transaction that consists of two or more actions. See also external succession. 


disk overflow 
The staging and linking of input messages to disk when the main storage queue has 
become saturated. 


display content | 
In the LIST or DETAIL command, a list of item names, subrecord names, or arithmetic 
expressions that indicate to UNIQUE what items or values to display at the terminal. 


display format command 
An input/output message structure especially suited for a cathode ray tube (CRT) type 
device. 
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ditto mechanism 
A shorthand means used in UNIQUE commands to identify a defined record by 
referring to part of the identifier of a previously identified defined record or to specify 
LIST or DETAIL parameters by referring to the appropriate part of the previous LIST or 
DETAIL command. | | 


downline load 
A process of obtaining programs from a load library and then sending them to the 
UTS 400 memory, cassette, or diskette. 


E 


edit table generator 
An offline IMS 90 utility program that writes a record in the named record 
(NAMEREC) file that contains the user’s definition of how online freeform terminal 
input is converted into fixed formats required by action programs. The edit table 
generator also checks input for data types, value ranges, and the presence of required 
fields. | 


explicit output message 
Output messages sent via the CALL SEND function. 


external succession : 
A method of succession in which an action program terminates by requesting that an 
output message be sent to the originating terminal and a specified action program be 
scheduled to proces the next input message form that terminal. Information tn the 
predecessor’s CDA is passed to the successor. 


- 


file 1/O functions | 
Those functions such as retrieval, insertion, deletion, update, and write, which are 
supported by the file management component of IMS 90. 


file management 
That IMS 90 component that issues requests to data management for user logical 
records required by action programs. File management interfaces with both action 
programs and data management, and provides services such as record locking, 
recovery, error processing, etc. 


function key 
A key on a UNISCOPE display terminal or UTS 400 terminal that is converted to a text 
input message. It can be used as a transaction code if the terminal is not in 
interactive mode or as a response to an output message to be passed on to a 
successive action program if the terminal is in interactive mode. 
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H 


hard copy format command 
An input/output dialog structure especially suited for a teletypewriter device. 


header line 
An output line containing item names that serve as column headers. 


hierarchical structure 
In IMS 90, a file structure with more than one type of record having one or more 
levels of subordinate records. The relationships between record types are parent, 
child, and fraternal. 


identifier 
The string of characters that is keyed in by a terminal operator to select a particular 
occurrence of a defined record. 


immediate internal succession | 
A method of succession in which the first action program indicates the name of a 
Succeeding action program without issuing an output message or deallocating main 
storage areas. The second action program then uses the same main mola? areas to 
complete and terminate action processing. 


implicit output message 
A message in the OMA when the CALL RETURN function is requested at action 
termination. 


IMSCONF 
A job procedure which generates and executes control streams that configure IMS 90 
using the user configuration specifications as input. 


input message area 
A required main storage area in the activation record consisting of a 16-byte control 
header and the variable length input message. 


inquiry operation 
An operation that retrieves and displays records from a file. The UNIQUE commands 
DISPLAY, LIST, MORE, and DETAIL are inquiry commands. 


integer 
A numeric literal that does not include any character positions to the right of the 
assumed decimal point. 


interactive mode 


The state of a terminal while a dialog transaction is in progress. Input messages do 
not contain transaction codes. 
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e interactive processing 


A method of information processing that involves a dialog between a terminal 
operator and IMS 90. 


internal message control (IMC) 


The IMS 90 component that controls message input/output processing and terminal 
command processing for action programs and IMS 90. ~ 


item 
A consecutive string of data bytes that is treated as a single entity by display, 
validation, and arithmetic functions. It appears in every occurrence of the type of 
record that contains it, in the same position, and with the same usage characteristics 
as specified in the data definition. The name of the item is displayed by UNIQUE as a 
column header when the item appears at a terminal. 


key 
One or more items contained in a record or in a repeating group item occurrence that 
distinguish that occurrence from all others in the same file or table. The key also 
determines where a new occurrence is to be inserted in an existing sequence of 
@ records or repeating group item occurrence. | - 


keyword parameter 


A parameter whose specification is identified by its name, rather than by its position 
in the operand field. 


L 


locked record 
A logical record which, by specification of the LOCK parameter at configuration time, 


is protected while being updated from being concurrently updated by another 
transaction. | 





lock-rollback-indicator 


A 1-byte value in the PIB which is set by the action program to select the record lock 
and roliback functions of IMS 90 action scheduling. 


logical record 


The actual record that exists physically on a user data file and accessed by standard 
access methods (DAM, SAM, MIRAM, IRAM, and ISAM). 
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Mi @ 


main storage queueing 
The process whereby messages are staged and linked in main storage. 


mandatory configuration parameter 
A parameter whose specification is required because omission of the specification 
renders IMS 90 inoperable. 





master terminal 
A control terminal used in monitoring IMS 90 and in controlling the IMS 90 
communications network. In single-thread IMS 90, the master terminal may be the 
console. : 





multithread IMS 90 
The capability of concurrently processing actions that come from different terminals. 


N 


named record file (NAMEREC) | 
An internal IMS 90 file containing configuration tables, data definition records, edit 
tables, and password definitions. @ 


O 


offline processing 
The operations that recover damaged or inconsistent user files. 


online processing 
The operations (such as startup/shutdown, internal message control, UNIQUE or user 
action program execution, and file management) that process transactions 
interactively. 


output delivery notice status code 
The hexadecimal value provided by IMS 90 in the fifth byte of the input message to 
inform continuous output user of the status of the last output message. 


output message area 
An optional main storage area in the activation record consisting of a control header 
and area for output message text. 


output-for-input queueing 
The operation of generating an output message via the SEND function to be @ 
scheduled as an input message on a terminal other than the initiating terminal. 
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password 


An installation-defined name that is associated with a specific defined file or subfile 
for security purposes. 


prefix 
One or more characters that are not a part of the record key that is stored on a disk, 
but which the terminal operator must key in as part of the identifier of a defined 
record. These characters are used to distinguish fraternal record types where the 
ranges of the values of the record keys overlap. 


pre-online processing 
The operations of IMS 90 utilities and processors (e.g., the NAMEREC utility, data 
definition processor, and configurator) that. prepare and configure the system for 
transaction processing. | 


primary part 
Those items of a defined record, including the identifier, that come from the record 
occurrence or repeating group item occurrence that is located by the identifier. The 
primary part must exist and is always the first part of the defined record to be read. 


print mode | 
A form of output printing in which what appears on an auxiliary device is the same as 
what appears on the screen of the primary device. 


print transparent mode _ | 
A form of output printing to an auxiliary device which is independent of the hardware 
limitations of the remote terminal screen. 


program information block (PIB) 
A required, predefined 48-byte main storage area within the activation record used to 
pass control information between IMS 90 and the user action program. 


pseudoterminal 
A virtual terminal created by the IMS 90 configurator for use in batch transaction 
processing. 


R 


record type 
The specific defined record layout when there are several possible record layouts in 
the same defined file. | 
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reentrant code am 
Shared code that is not self-modifying allowing concurrent use by several threads. © 


repeating group item 
An item for which an OCCURS clause appears in the data division. 


resident subprogram 
A user-written program that resides in main storage, is called by an action program or 
another subprogram, and returns control to the calling program. 


S 


screen format services 
A method of displaying predefined formatted screens at a terminal. IMS 90 places the 
screen formats into the action program’s OMA when a BUILD function call is issued. 


selection criteria 
In the LIST and DETAIL commands, conditional expressions that determine which 
records are to be displayed in response to these commands. 


serially reusable 
A program that, when it is in main storage, can be executed by another thread after 
the current thread has terminated its use. & 


shared code 
Code whose self-modification observes certain restrictions enabling action scheduling 
to switch the use of that code from one thread to another whenever a function 
request is made. This effectively allows concurrent use by several threads. 


simple transaction 
A transaction that consists of a single action. 


single-thread | 
The capability of processing a single action at a time, from initiation to termination of 
the action program. 


solicited message 
A message that is a reply to previous input 


standard terminal 
A production terminal used for entering commands and receiving messages during 
transaction processing. | 


Statistical function 
Functions provided by the UNIQUE LIST command to derive totals, record counts, 
averages, minimums, and maximums. 
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status code 
A 2-byte binary integer value in the PIB indicating the completion status of a request. 
This code is interpreted differently for file 1/O functions and explicit message output. 


stored record name 
The name of a group item in the data division that describes the logical record source 
of the defined record. 


subfile 
In a defined file, a subset of defined records or subrecords that provides an alternative 
and more restrictive access than the defined file. 


subprogram 
A separately compiled module that is called by an action program or another 
subprogram. It can either be linked with the calling program or made resident, in 
which case it can be either reentrant or serially reuseable. It performs functions 
common to two or more action programs. 


subrecord 
A variant of a defined record, that allows alternative and more restrictive access. 


subrecord name 
The name of a subrecord that provides an alternative to defined record name in the 
content clause of the LIST command. 


success unit 
The sequence of actions over which record locks are held starting with the input of a 
message or a rollback point, and ending with the next rollback point or transaction 
termination. 


succession 

The mechanism that provides the dynamic sequencing of action programs in a 
transaction. Immediate internal succession provides the linkage between two action 
programs in an action with no modification in resource allocation. Delayed internal 
succession provides the linkage between two actions with the output message from 
the first action queued as input to the successor action. External succession provides 
the linkage between actions in a transaction, with messages sent to and from the 
initiating terminal. 


successor-ID | 
A 6-byte field in the PIB indicating the name of the action program to be activated 
when the current action program terminates. 


suffix | 
A string of characters that occupies the least significant character positions of a 
record key as stored in disk. These characters are not included in the identifier keyed 
in by the terminal operator; therefore, they must be literally added by DRM. They are 
specified in the FILL KEY statement. 


UP-8614 Rev. 1 SPERRY UNIVAC O0S/3 Glossary 12 
IMS 90 APPLICATIONS 


supplement ® 
Those additional items of a defined record that come from a record or a repeating 
group item occurrence that is different from the source of the primary part. The 
source of the supplement is located by a pointer that is constructed from one or more 
items of the primary part or of previously read supplements. 


supplement name 
The name that identifies a supplement within a data definition 


T 


terminal commands 
There are standard and master terminal commands. Standard terminal commands 
may be issued from any terminal to control the flow of messages at the terminal. 
Master terminal commands may be used only at the master terminal to control the 
overall system and communications network. 


terminal control table (TCT) 
Describes the terminal and transaction environment and the program status. 


termination indicator | 
A 1-byte value in the PIB which indicates the type of termination for the current 


action program © 


test mode 
A terminal state in which there is no physical alteration to data files; file updates are 
simulated. 


thread 
A unit of control for the sequence of events needed to complete the processing of an 
action. 


total line 
An output line containing line names, their requested totals, and other statistical 
functions. 


transaction 
A sequence of one or more actions that are related through delayed internal or 
external succession. 


transaction code 
One to five alphanumeric characters, with the first character alphabetic, used to 
identify and initiate a transaction. 


transaction control interface (TCl) 
An interactive communications interface designed for IMS 90. 


transaction terminal table 
A table used to pass information between IMS 90 and ICAM. 
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transaction ID 
The unique date-item stamp of the initial input message in a transaction 


U 


uniform inquiry data element (UNIQUE) 
A set of action programs supplied by Sperry Univac that retrieves and updates data in 
files. 


UNIQUE commands 
A series of commands that facilitate the manipulation of defined files. 


unsolicited output 
All messages that are not responses to previous input (e.g., requests from one 
terminal to be transmitted to another terminal). 


update format 
A format, displayed by UNIQUE, that reveals to the terminal operator certain 
characteristics of each item that can be updated. These characteristics include length 
and decimal placement. 


update operation 
An operation that causes a record in a file to be deleted, added, or changed. The 
UNIQUE commands DELETE, ADD, and CHANGE are update commands. 


V 


validity test 
An acceptance test performed by defined record management on new item values 
when a defined record is added or updated. The new item value is compared to 
ranges that have been specified in VALUE statements in the data definition. 


W 


work area (WA) 
An optional main storage area within the activation record generally used by sharable 
or reentrant action programs for file I/O logical record areas and working storage. 
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Index 
Term Reference Page Term Reference Page 
A AUX-FUNCTION byte, OMA 
continuous output 3.10.1.1 3—86 
Action line disconnect 3.11 3—100 
definition 1.1 1—1 output-for-input queueing 3.10.2 3—98 
delayed internal succession 3.1.2.4 3—7 settings Table 3—16 3—8/7 
external succession 3.1.2.2 3—5 
immediate internal succession 3.1.2.3 3—6 Auxiliary device 
simple transaction 3.1.2.1 3—4 condition codes Table 3—20 3—98 
continuous output 3.10.1.1 3—86 
©@ Action program implicit output 3.9 3—82 
accessing data files 2.1.1 2—2 normal output 3.6.2 3—4] 
BAL 3.4 3—26 
COBOL 3.2 3—11 AUXILIARY-DEVICE-ID field, OMA 
environment 314 3—2 continuous output 3.10.1.1 3—86 
IMS 90 transactions 5.3 5—17 normal output 3.6.2 3—4l 
reusability 3.1.3 3—10 output-for-input queueing 3.10.2 3—98 
RPG Il 3.3 3—15 
transaction structure 3.1.2 3—3 
Action scheduling 3.1.1 3—2 
Activation record 3.6 3—30 
ADD command (UNIQUE) 6.2.8 6—14 
ALLOW ADD AND DELETE statement 
defined record definition 2.3.5.11 2—30 
subrecord definition 2.3.8.3 2—45 
ALLOW CHANGE option B 
item definition 2.3.6.5 2—36 
subitem definition 2393 2—4g8 | BAL action program 
example 3.4 3—26 
ALSO statement 2.35.12 2-30 function requests 342 oe 
linkage conventions 3.4.1 3—26 
Alternate terminal command (ZZALT) 5225 Sl reentrant program considerations se ore! 
subprogram interface 3.9.3 3—30 
Application management 3.11 3—2 terminating 3.4.2 3—2] 
Audit file 337 3—76 Basic assembly language program See BAL action 


program. 
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BATCH parameter statement 132 7—6 COBOL action program 322 3—12 
data definition processor 23.1 2—11 
Batch transaction processor edit table generator 42.1 4—] 
diagnostic messages Table 7—1 /—16 file 1/0 functions 3.8.1 3—50 
input messages 74.1 7—10 general Appendix A 
invoking 1323 7-1] 
offline mode 75 7—11 Commands, UNIQUE 6.2 6—4 
online mode 76 7—12 
output Tz 7—| Communications output printer (COP) 
parameter statements 732 7—6 auxiliary device condition codes Table 3—20 3—98 
processing 7.2 7—] continuous output 3.10.1.1 3—86 
implicit output 3.9 3—82 
Build function call 3.14.2.1 3—116a normal output 3.6.2 3—4] 
Common storage area files 3.89 3—81 
Condition codes, auxiliary device Table 3—20 3—98 
Cc Conditional expression, LIST command 6.2.10 6—25 
CALL macro 3.4.2 3—2/7 CONTAINS statement 2.3.10.2 2—50 
3.4.3 3—27 
Continuity data area (CDA) 
CALL statement 3.2.4 3—14 delayed internal succession 3.1.2.4 3—/ 
description 3.3.1.4 3—?21 
CANCEL command (UNIQUE) 6.2.7 6—13 external succession 31-22 3—5 
function 3.1 3—2 
Cassette/diskette length 365 3—AT 
action program interface 3.10.1.1 3—87 


auxiliary function byte settings 
message text for searching 
message test for search and 


Table 3—16 3—87 
Table 3—17 3—9] 


Continuous output 
delivery notice scheduling 
devices supported 


3.10.1.3 3-93 
3.10 3—85 


positioning Table 3—18 3—92 example action programs 3:10] 3—119 
3.15.2 3—122 
CHANGE command (UNIQUE) 6.2.9 6—22 implicit output 3.9 3—82 
line disconnect 3.11 3—100 
Change master terminal command (ZZMCH) 5.2.1.7 5—8 output-for-input queueing 3.10.2 3—98 
SEND function ho | 3—82 
CLOSE command (UNIQUE) 6.2.2 6—/ terminating 3.10.12  3—92 
COBOL action program Control block 
compiling 3.2 3—11 multithread Fig D—3 D—6 
examples 3.14 3—111 single-thread Fig D—-1 D—2 
format 3:2 3—11 
function calls 3.8 3—A49 Control characters, hard copy device 5.12 5—2 
linkage section 3.2.3 3—14 
link editing 3.7 3—48 Control table, single- and multithread 
procedure division 3.2.4 3—14 terminal Fig D—2 D—4 
restrictions S22 3—12 
screen format services 3:15.5 3—140 | COPY library 
_ Fig. 3—31 3—140a COBOL action program 3.2 3—11 
terminating 3.2.4 3—14 data definition execution 2.5.1 2—65 
working-storage section 3.2.2 3—12 DICE sequences Fig. 3—23 3—122 
. IMA contro! header Fig. 3—12 3—46 
Coding rules OMA control header Fig 3—-10 3—43 
BAL action program 3.4.1 3—26 PIB Fig 3—8 3—32 
batch transaction processor 74.1 7—10 
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DAM files 
data definition source 
functions supported 
random file functions 


Data base management system 90 (DMS 90) 


DATA-DEF-REC-NAME field, PIB 


Data definition 
data division 
definition division 
examples 
identification division 
language 
NAMEREC file 
overview 
processor 


Structure 
Data definition language 


Data definition processor 
coding rules 
error processing 
execution 
options 
output listing 
run streams 


Data definition record 
creating 
retrieved by DRM 
Data files, accessing 
DCT 500 Data Communications Terminal 
continuous output 
output delivery notice 
DCT 1000 Data Communications Terminal 
continuous output 
output delivery notice 
Defined file definition 
DEFINED-FILE-NAME field, PIB 
DEFINED FILE statement 


Defined files 
access by action programs 
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2.3.3 2—15 
Table 3—10 3—49 
3.8.3 3—5/7 
See DMS 90 
data base. 
3.6.1.6 3—A40 
2.3.2.2 2—15 
2.3.2.3 2—15 
24 2—5l 
2.3.2.1 2—14 
2.3 2—11 
25 2—65 
2.1 2—1 
See data 
definition 
processor. 
2.3.2 2—14 
2.3 2—i1 
2.3.1 2—11 
2.5.4 2—/0 
2.5.2 2—67 
251 2—65 
2.5.3 2—6/7 
2.5.2 2—6/7 
— 212 . 2—5 
2.1.1 2—2 
2.1.1 2—3 
3.10 3—85 
3.10.1.3 3—93 
3.10 3—85 
3.10.1.3 3—93 
2.3.4 2—17 
3.6.1.6 3—40 
2.3.4.1 2—17 
2.1 2—1 


Term 


accessed by UNIQUE 

data definition processor 
output listing 

description 

examples 

hierarchical structure 


Defined record 
accessing 
derivation from logical records 
description in data definition 
relationships 


Defined record area 
description 
function 


Defined record definition 
Defined record identifier 


Defined record management (DRM) 
data flow 
overview 
random file functions 
returns to action program 
sequential file functions 


DEFINED RECORD statement 


Delayed internal succession 
batch transaction processing 
TERMINATION-INDICATOR, PIB 
transaction structure 


DELETE command (UNIQUE) 


DELETE function 
indexed files 
oarameters 
random file functions, DRM 
random files 
sequential file functions, DRM 


DELIVERED-RECORD-TYPE byte 


Delivery notice scheduling 
auxiliary device condition codes 
continuous output 
example action program 
recovery considerations 
Status codes 


Destination terminal 
auxiliary device 
implicit output 
output-for-input queueing 
SEND function returns 
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6.1.2 


Fig. 2—38 
2.2 | 
2.4 

2.2.1 


2.1.1 
2.2.2 
2.2.2 
2.2.1 


3.6.6 
3.11 


2.3.9 


2.2.2 


2.1.1 
2.1 
3.8.6.1 
3.8.5.2 
3.8.5.3 


2.3.9.1 


Vid 
3.6.1.4 
3.1.2.4 


6.2.5 


3.8.2.1.4 
3.8.3.1.4 
3.8.3.1.4 
3.8.5.2 
3.8.5.3 


3.8.5.1 


Page 
6—3 


2—68 
2—9 
2—951 
2—6 


2—2 
2—/ 
2—/ 
2—6 


3—48 
3—3 


2—20 


2—] 


2—2 
2—1 
3—66 
3—68 
3—/0 


2—20 


3—54 
3—60 
3—60 
3—68 
3—/0 


3—66 


Table 3—20 3—98 


3.10.13 
3.1.15.3 
3.10.14 


3—93 
3—128 
3—94 


Table 3—19 3—95 


3.6.2 
3.9 
3.10.2 
3.9.2 


3—A1 
3—82 
3—98 
3—83 
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DETAIL command (UNIQUE) 6.2.12 6—33 | DSECTs 
accessing 3.6 3—30 
Detailed status codes ZCHDICT (terminal control table) Fig D—2 D—4 
defined record management 3.8.6.1 3—73 ZM#DIMH (IMA control header) Fig. 3—13 3—46 
DETAILED-STATUS-CODE field, PIB 3.6.1.2 3—35 ZM#DOMH (OMA control header) Fig. 3—11 3—43 
file [/0 functions Table 3—8 3—35 ZM#DPIB (PIB) Fig 3—9 3—33 
SEND function 3.9.2 3—83 ZT#DTHCB Fig D—1 D—2 
Fig D—3 D—6 
Device-independent control expressions See DICE sequences. 
Dump, snapshot 3.12 3—100 
Diagnostic severity codes, data 
definition processor 2.9.4 2—/0 Dynamic sessions 
initiating 5.4 5—31 
Dial-in line, disconnecting oe 3—100 terminating 5.4 5—32 
Dialog 
transaction 3.1.2.2 3—5 
UNIQUE 6.1.1 6—1 
DICE sequences 
action programs 3.1.4 3—10 
batch transaction processor 742 7-11 
continuous output 3.10.1.1 3—86 
filed in COPY library, example Fig. 3—23 3—122 
input message editing 44 4—8 E 
transmitting from hard copy device O21 5—2 
; ; Edit table generator 
Direct access method See DAM files. sari 421 ae 
= error processing 4.3.2 4—6 
DISPLAY command (UNIQUE) 6.2.3 6—/ axeculing 13 45 
; function 4) 4—] 
se 6281 6—14 input message editing 44 4—8 
CHANGE command 6.29.1 622 Input parameters vce anes 
sample application 45 4—9 
sale 512 52 Embedded data, batch processor 7.3.2 7—6 
function keys 5.1.5 5—5 Fritry point 34] 396 
DLMSG transaction code is eo 5—20 . 
Error diagnostics 
DLOAD transaction code 5.3.3 5—20a batch transaction processor Table 7—1 7—16 
data definition processor Table 2—2 2—71 
DMS 90 data base edit table generator 4.3.2 4—6 
accessing 9] oa} See also error processing. 
source in data definition 23 2—11 . 
; Error processing 
Downline load batch transaction processor 78 7—19 
action programs 313] 3—105 continuous output 3.10.14 3—94 
DLOAD transaction code 5 33 5—20 data definition processor 2.5.4 2—/0 
initialization 4344 3109 defined record management 3.8.5.1 3—67 
processing 3.13.1.2 3—110 detailed status codes 3.6.1.2 3—35 
ZUKLOD program 5.3.3 5—20a edit table generator 4.3.2 4—6 
involuntary termination 3.6.1.4 3—37 
DRM See defined record SEND function 3.9.2 3—83 
management. snapshot dump 3.12.1 3—101 
Status codes 3.6.1.1 3—34 
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ESETL function 
defined files 
indexed files 
random files 


ETAB keyword, edit table generator 
Expanded input editor 
Explicit output 
External succession 
continuous output 
line disconnect 


TERMINATION-INDICATOR, PIB 
transaction structure 


F 


FIL keyword, edit table generator 
File closing 

File descriptors 

File 1/0 functions 


defined files 


formats and rules 
indexed files 
1/0 error returns 
random files 


File management, IMS 90 
access methods supported 
data flow 

File opening 

File recovery, online 

File sharing 

FILL KEY statement 


defined record definition 
supplement definition 
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3.8.5.3.3 
3.8.2.2.3 
3.8.3.2.3 


422 


3.9.1 


3.10.1.2 
3.11 
3.6.1.4 
3.1.2.2 


4.2.2 
3.8.8.1 


3.8.8.2 


3.8.0 


3.8.5.2. 


3.8.5.3 
3.8.1 
3.8.2 
3.8.6.1 
3.8.3 
3.8.4 


3.8 


2.1.1 


3.8.8.1 


3.8.6 


3.8.8.4 


2.3.5.10 
23:19 


Page 


3—/2 
3—9/ 
3—63 


3—8/ 
3—101 
3—37 
3—5 


3—56 
3—68 
3—/0 
3—50 
3—51 
3—73 
3—5/ 
3—65 


2—29 
2—A4} 


Term 


FOLLOWS statement 
Fraternal defined records 


Freeform input, editing 


FROM CONTROL BREAK statement 


FROM REPEATING GROUP statement 
defined record definition 
supplement definition 


FROM statement 
defined record definition 
supplement definition 


Function keys 
entering from terminal 
input message format 


Function requests 
CALL macro 
CALL statement 
RETURN function 
SEND function 
SNAP function 
SUBPROG function 


ZGHCALL macro 


GET/GETUP function 
indexed files 
random file functions, DRM 
random files 
relative files 
sequential file functions, DRM 
sequential files 
sequential, relative files 


GETLOAD function 


Global network terminal commands 
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2.3.5.9 


2.2.1 


Page 


2—28 


2—6 


See edit table 


generator. 


2.3.5.3 


2.3.5.4 
2.3.1.3 


2.3.5.2 
2.3.1.2 


5.1.5 
3.5.2 


eo 4 
3.5.3 
3.5.3 
3.9.1 
3.12.2 
3.9.2 
3.5.3 
3.4.2 


3.8.2.1.1 
3.8.2.1 

3.8.5.2.1 
3.8.3.1.1 
3.8.4.1 

3.8.5.3.2 
3.8.3.2.2 


3.13.1 
3.13.1.2 


2—22 


2—23 
2—39 


2—21 
2—39 


9-9 
3—26 


3—29 
3—30 
3—30 
3—82 
3—101 
3—29 
3—30 


_ 3-27 


3—52 
3—51 
3—68 


3—58 


3—64 
3—7] 
3—62 


3—105 
3—110 


5—31 
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Halt command (ZZHLT) 
HANGUP program 


Hard copy format 
ADD command 
CHANGE command 


Hard copy terminal 
entering message 
function keys 


HIDDEN option 


Hierarchical structure, defined file 
description 
examples 


IBM 3270 display station, with 
UNIQUE 


Identifier, defined record 


IDENTIFIER statement 
IMA 


Immediate internal succession 
batch transaction processing 
TERMINATION-INDICATOR, PIB 
transaction structure 


Implicit output 
continuous output 
description 


IMS READY message 


IMS 90 
applicability 
operations 
overview 
user activities 


IN parameter, batch processor 
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6.2.8.2 
6.2.9.2 


31.2 


9.15 


2.3.6.3 


244 
224 


6.2.8 
6.2.9 


2.2.2 


2.3.6.1 


Page 


I—16 


3—100 


2—32 


See input message 


dared. 


7.2 
3.6.1.4 
3.123 


310.1 
3.9 


~J 


I—5 
|—2 
I—] 
I—3 


Term 


Indexed random access method 


Indexed sequential access method 


Input message 
transaction code 
transaction structure 
transmitting 


Input message area (IMA) 
BAL format 
COBOL format 
description 


Input message editing 


entering message from terminal 


sample application 


INSERT function 
DAM files 
defined files 
ISAM files 


Interactive mode 


Internal message contro! 
returns from SEND function 
SEND function 


Internal succession 
delayed 


immediate 


I/O functions 
defined record management 
formats and rules 
indexed files 
relative files 
sequential files 


Item definition 
ITEM statement 
item definition 


subitem definition 


Item status byte, data definition 
processor output listing 
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See IRAM files. 
See ISAM files. 
5.1.3 9—3 
3.1.2.1 3—4 
Date 5—2 
Fig. 3—13 3—46 
Fig. 3—12 3—46 
3.6:3 3—45 
44 4—8 
45 4—9 
3.8.2 3—48 
3.8.6.2 3—69 
3.8.3.1 3—52 
5.1.5 5—5 
3.9.2 3—83 
3.9.1 3—82 


See delayed internal 


succession. 


See immediate 
internal succession. 


3.8.5 


3—65 
3—30 
3—51 
3—5/ 
3—63 
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J 


JUS keyword, edit table generator 


K 


KEY keyword, edit table generator 


L 


LEN keyword, edit table generator 
Lexicon, UNIQUE 
Line disconnect 
Link editing action programs 
Linkage conventions 
BAL action program 
BAL subprogram . 
COBOL action program 
COBOL subprogram 
LIST command (UNIQUE) 
Load error byte definition 
-Lock-for-transaction 
LOCK-ROLLBACK-INDICATOR, PIB 
description 
online recovery 
Locks, logical record 
Logical files 
data flow 
source in data definition 
Logical record lock 
Logical records 


accessing 
described in data definition 


SPERRY UNIVAC OS/3 
IMS 90 APPLICATIONS 


Reference Page 


4.2.2 4—4 
42.2 4—3 
4.2.2 4—3 
Appendix B 

3.11 3—100 
3.7 3—48 
3.4.1 3—26 
35:3 3—30 
3.2.3 3-14 
3.5.2 3—29 
6.2.10 6—25 


Table 3-21 3—108 


3.8.7.2 3—7/ 
3:6.155 3—39 
3.8.6 3—/2 
3.0.1 3—/6 
cack 2—2 

2.3 2—11 
3.8.8 3—76 
2A 2—2 

20:3 2—19 


Term 


Main storage areas 
activation record 
dynamically allocated 
MAN keyword, edit table generator 
Master terminal commands 
MAX keyword, edit table generator 
Message switching 
MIN keyword, edit table generator 
MIRAM files 
indexed file functions 
relative file functions 


sequential file functions 


MORE command (UNIQUE) 


Multiline terminal message handling 


MUST ADD option 
item definition 
subitem definition 


Named record (NAMEREC) file 
data definition records 
edit tables 

NEXT command (UNIQUE) 


Normal termination 


Index 7 
Update A 


Reference 


3.6 
3.1.1 


9.3.1 
4.22 
3.8.2 
3.8.3 
3.8.4 


6.2.11 


JZ 


2.3.6.4 
2.3.9.2 


Page 


3—30 


2—35 
2—4] 
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Term 


O 


OF statement 

Offline mode, batch transaction processing 
Offline processing 

OK command (UNIQUE) 


OMA 


Online file recovery 
Online mode, batch transaction processing 


Online processing 
functions 
initiating 


OPEN command (UNIQUE) 


Output, auxiliary device 
continuous 
implicit 
normal 


Output-for-input queueing 


Output message 
continuous output 
delivery notice scheduling 
explicit output 
implicit output 
output-for-input queueing 
SEND function 


Output message area (OMA) 
BAL format 
COBOL format 
continuous output 
description 
SEND function 


Reference Page 


2.3.8.2 2—45 
75 7—11 
ie 1—3 

6.2.6 6—12 


See output message 
area. 


3.8.6 3—72 
76 7—12 
1.1.1.2 1—2 
5.1.1 I—1 
6.2.1 6—5 
3.10.1.1 3—86 
3.9 3—82 
3.6.2 3—41 
3.10.2 3—98 
3.10.1.1 3—86 
3.10.1.3 3—93 
3.9.1 3—82 
3.9 3—82 
3.10.2 3—98 
3.9.1 3—82 
Fig 3—11 3—43 
Fig 3—10 3—43 
3.10.1.1 3—86 
3.6.2 3—4l1 
3.9.1 3—82 


Term 


Parameter list 
BAL action program 
resident subprogram 


Parent/child relationship 
PARENT statement 


PASSWORD option 
DEFINED FILE statement 
SUBFILE statement 


PIB 


POINTER statement 
defined record definition 
supplement definition 


Polled and nonpolled devices 
continuous output 
delivery notice status codes 


POS keyword, edit table generator 
PREDICTED-RECORD-TYPE byte 
PREFIX statement 

Pre-online processing 


Print mode 
continuous output 
normal output 


Print transaction 
continuous output 
example action programs 
output-for-input queueing 


Print-transparent mode 
continuous output 
normal output 


Program information block (PIB) 
BAL format 
COBOL format 
field descriptions 
function 


Pseudoterminal, batch 


PUT function 
defined files 
indexed files 
relative files 
sequential files 


Reference Page 


3.4.1 3—26 
3.5 3—28 
2.2.1 2—6 

2.3.5.6 2—25 
2.34.1 2—17 
2.3.10.1 2—49 


See program 
information block. 


2.3.5.8 2—2] 
2.3.7.4 2—A40 
3.10.1.3 3—88 
Table 3—19 3—95 
4.2.2 4—4 
3.6.1.2 3—36 
2.3.5./ 2—26 
1.1.1.1 1—2 
3.10.1.1 3—86 
3.6.2 3—4l 
3.10.1 3—86 
3.14.3 3—118 
3.10.2 3—98 
3.10.1.1 3—86 
3.6.2 3—45 


Fig 3—9 3—33 


Fig 3-8 3-32 
3.6.1 3—31 
3.1.1 3—2 

2 7—1 

3.8.5.2.2  3—68 
3.8.2.1.2 3—53 
3.83.12 3—59 
3.8.4.2 3—64 
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Term 


REBUILD function call 
Record locking 
RECORD-TYPE field, PIB 
Recovery, online 
Reentrant program 
Register contents 

BAL action program 

BAL subprogram 

snapshot dumps 
Repeating group item 


example 
FROM REPEATING GROUP statement 
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Reserved words, data definition 


Resident subprogram 


RETURN function 
BAL action program 
BAL subprogram 
COBOL action program 
COBOL subprogram 





Reusability 
action program 
reentrant BAL program 
Subprogram 


ROLE IN UPDATE statement 


Rollback 
LOCK-ROLLBACK-INDICATOR, PIB 
online recovery 
prefix area format 


RPG Ii action program 
compile and link 
examples 


execution 
files, logical and defined 
ICAM network generation 








Reference Page Term 
IMS 90 configuration 
interface areas 
3.14.3 3—118a restrictions 
snapshot dump (screen not found) 
3.8./ 3—76 specifications forms 
3.8.5.1 3—66 
3.8.6 3—/72 
3.4.3 3—2] 
S 
4 — 
ae aa SAM files 
3121 3—101 functions supported 
_~ \/0 functions 
2442 959 Screen bypass device 
—623.54 2—23 ; ; 
1373 939 Screen formatting services 
BUILD function call 
Maier ores COBOL and BAL action programs 
See subprogram, description 
user-written. example, COBOL 
REBUILD function call 
342 327 RPG Il action programs 
353 330 support of auxiliary devices 
ar — Segmented output 
SEND function 
313 3—10 batch transaction processing 
343 397 description and format 
35] 398 output-for-input queueing 
ee returns from 
eer a SEP keyword, edit table generator 
36.15 339 Sequential access method 
3.8.6 3—/2 | 
ae SETL function 
ee a defined files 
indexed files 
Fig, Car - C4 relative files 
Fig 3—31 3—140 
Fig 3-39 ey SETLOAD function 
Fig. 3—33 3—143 
ig. 3-34 3—14 
i sete hag | SHOW command (UNIQUE) 
ig 3—36 3—14 
ie ss ie Shutdown command (ZZSHD} 
Fig. 3—3 —149 
Fig i a Single-thread processing 
Fig. C— C—11 
Ae y 32] SNAP function 
Fig C—1 C—2 


Index 9 
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Reference 


Fig. C—2 
3.3.1 

3.3.4 

Fig. 3—20B 
3.3.3 


Page 


C—3 
3—16 
3—26 
3—118c 
3—23 


Table 3—10 3—49 


3.8.4 3—63 
3.10.3 3—100 
3.14.2.1 3—116 
3.14.2 3—113 
3.15.5 3-—-140 
3.14 3—111 
3.14.1 3—112a 
Fig 3—31 3—140a 
3.14.2.2 3—118a 
3.14.3 3—118b 
Table 3—22 3—112 
Bld 5—4 
ys 7—1 
3.9.1 3—82 
3.10.2 3—-98 
3.9.2 3—83 
4.22 4-2 
See SAM files. 
3853.1 3-70 
3.8.2.2.1 3—55 
3.8.3.2.1 3—61 
3.13.1 3—105 
3.13.1.1 3—109 
6.2.13 6—34 
5.2.29 5—15 
Appendix D 

3.12.2 3—101 
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Term 


Snapshot dump 
abnormal termination 
call snap 
generating 


S$SOFF global terminal command 
Solicited output 
$$SON global terminal command 


Statement conventions 
data deftnition processor 
file 1/0 functions 
general rules 


Statistical functions, LIST command 


Status byte 


Status codes 
defined record management 
output delivery notice 
SEND function 
STATUS-CODE field, PIB 


See also individual file 1/0 functions. 


Status messages 


Subfile 
data definition processor 
output listing 
definition 
example 


SUBFILE statement 
Subitem definition 


SUBPROG function 
BAL action program 
COBOL action program 


Subprogram, user-written 
BAL action program interface 
COBOL action program interface 
filing 
function 
residence 
reusability 


Subrecord 
definition 
example 


SUBRECORD statement 
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Reference Page 
3.12.1 3—101 
3.12.2 3—101 
3.12 3—100 
5.4 5—31 
5.1.4 5—4 
5.4 5—3] 
2.3.1 2—1] 
3.8.1 3—50 
Appendix A 

6.2.10 6—25 
See item status 
byte. 

3.8.5.1 3—66 
Table 3—19 3—95 
3.9.2 3—83 
3.6.1.1 3—34 
a a 5—18. 
Fig. 2—38 2—68 
2.3.10 2—49 
2.4.2 2—54 
2.3.10.1 2—49 
2.3.9 2—46 
3.5.3 3—30 
3.5.2 3—29 
35.2 3—30 
35:2 3—-29 
35 3—28 
35 3—28 
35.1 3—29 
3.4.1 3—29 
2.3.8 2—44 
2.4.2 2—54 
2.3.8.1 2—44 


Term 


Subschema 


Success unit 


Succession 
delayed internal 
external 
immediate internal 
SUCCESSOR-ID field, PIB 
TERMINATION-INDICATOR, PIB 


SUCCESSOR-ID field, PIB 
calling subprogram 


continuous output 
description 


Supplement, defined file 
definition 
example 


SUPPLEMENT statement 


Switched output 
description 
sent to alternate terminal 
SWITCH transaction code 


SWITCH transaction code 
SYSLST file, batch processor output 


SYSOUT file, batch processor output 


TELETYPE terminal 
continuous output 
output delivery notice 


Terminal commands 
master terminal commands 
standard terminal commands 
summary 


Terminal printer (TP) 


Terminai-to-terminal communication 


TERMINATION-INDICATOR, PIB 


Index 10 
Update A 


Reference 


See DMS 90 
data base. 


3.6.1.6 


9.1.4 
D220 
9.3.1 


i2 


7.2 


3.10 
3.10.1.3 


9.2.2 
5.2.1 
Table 5—2 


Page 


3—85 
3—93 


on qn 


—9 
—/ 
—6 


See communications 
output printer. 


9.3.1 
3.6.1.4 





9—18 
3—37 
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Term Reference Page Term Reference Page 
Test mode UNISCOPE display terminal 
description 3.8.8.6 3—81 auxiliary device condition codes Table 3—20 3—98 
ZZTMD terminal command 5.2.1.4 5—] continuous output 3.10 3—85 
function keys. sales, 5—5 
Transaction output delivery notice 3.10.1.3 3—93 
definition Pt 1—1 
dialog 3.1.2.2 3—5 Universal Terminal System 400 (UTS 400) See UTS 400 
IMS 90 J 9—17 terminal. 
initiating 5.1.3 5—3 
rollback 3.6.1.5 3—39 Unsolicited output 
simple S124 3—4 batch transaction processing 7.2 7-1 
structure 3.1.2 3—3 description 5.1.4 5—4 
Transaction code Update state, terminal 6.2.8 6—14 
action scheduling 3.1.2.1 3—4 
entering from terminal 513 5—3 UPS! byte, edit table errors 43.1 4—6 
function keys 5.1.5 5—5 
IMS 90 5.3 5—17 User data files, accessing 2.1.1 2—2 
Transaction control section (TCS) DSECT User-written action program See action 
auxiliary device condition codes Table 3—20 3—98 programs. 
delivery notice scheduling 3.10.1.4 3—94 | 
delivery notice status codes Table 3—19 3—95 | User-written subprograms See subprograms, 
listing Fig. 3—16 3—97 user-written. 
Transaction processing UTS 400 terminal 
batch | 72 | auxiliary device condition codes Table 3—20 3—98 
description | 11 | continuous output 3.10 3—85 
UNIQUE | 6.2 6—A DLOAD transaction code 5.3.3 5—20a 
downline loading 3.13 3—105 
Transaction structures 9.3.3 5—20 
combination 3.1.2.5 3—9 function keys 9-15 Id 
delayed internal succession 3.1.2.4 3—7 screen bypass device 3.10.3 3—100 
external succession 322 3—5 
immediate internal succession 3.123  3—6 
simple 3.1.2.1 3—4 
TYP keyword, edit table generator 4.2.2 4—5 
TYPE statement 2.3.9.9 2—24 
V 
VALUE statement . 
item definition 2.3.6.6 2—36 
Subitem definition 2.3.9.4 2—48 
U 
Uniform inquiry update element See UNIQUE. 
UNIQUE 
accessing data files 2.1.1 2—3 
commands 6.2 6—4 
concept 6.1 6—1 
dialog 6.1.1 6—1] 
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ne ee PM 
Term Reference Page Term Reference Page 
W | ZUKLOD downline load action program 5.3.3 5—20a 
Work area ZZALT master terminal command 5.2.25 5—11 
description 3.6.4 3—47 
function 3.11 3—3 ZZBTH master terminal command 5.2.2.8 5—15 
length 3.6.1.6 3—40 7.6.1 7—13 
ZZCLS master terminal command 5.2.2.6 5—13 
ZZCNC terminal command 5.2.1.6 5—8 
ZZDWN master terminal command 5.2.2.2 5—10 
ZZHLD terminal command §2.1:2 5—/] 
ZZHLT master terminal command 5.2.2.10 5—15 
Z ZZNRM terminal command 5.2.15 5—8 
ZG#CALL macro, BAL action program 3.4.2 3—27 ZZOPN master terminal command 5.2.2.7 5—14 
3.4.3 3—27 
ZZPCH master terminal command S220) 5—15 
ZHHEDT utility See edit table 
generator. ZZRDY terminal command 5.2.1.3 5—] 
ZSTAT transaction code ZZRSD terminal command 5.2.1.1 5—/ 
descripti 5.3.4 5—22 | 
ec 5342 5—30 ZZSHD master terminal command 5.2.2.9 5—15 
file status display screen Fig 5—1 5-23 
function key operation 5.34.1 5—29 | 2ZICT master terminal command 
HELP screen, page 1 Fig 5—5 526 batch processing use 7.6.3 7—15 
HELP screen page ? Fig. 5—6 5—27 function and format 5.2.2.4 5—11 
menu, input screen Fig 5—8 5—29 . 
orice ecesh Fig 5—7 527 | ZZTMD terminal command 5214 9 5-7 
rogram status display screen Fig 5—2 5—24 
ea errors ea ae 5—5 5—30 ZZTST master terminal command 5.2.2.3 5—10 
terminal status display screen Fig 5—4 5—26 . 
transaction status display screen Fig 5—3 5—25 ZZUP master terminal command 9.2.2.1 9 
unrecoverable errors Table 5—6 5—31 
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